Source : ddx-documentation/assistant-diagnosis-wiring.md
One map of what the assistant turn is made of, for the four turns a doctor can start: typed, case-bound typed, voice, case-bound voice. Written from the merged code (plans `osprey-assistant-engine` and `osprey-assistant-casework`); code beats this page. Glossary: `CONTEXT.md`. Engine overview: `osprey-engine.md`. Settings: `settings.md`. The assistant never writes a kernel case. `dx_case_create` is a proposal: the engine emits an approval-gated card, the web card creates the case through the BFF, then binds the chat (`?case=`). ## 1. The four turns | Column | Typed | Case-bound typed | Voice | Case-bound voice | |---|---|---|---|---| | Agent | picked user agent, else `assistant.agent.defaultId` | none (`noAgent: true`) | as typed | none (`noAgent: true`) | | Persona | session persona, else `assistant.persona.defaultId` | `dx-assistant:<tenant>` (web sends it) | as typed | `dx-assistant:<tenant>` (voice body adds it when the tenant has one) | | Lane | router verdict; `diagnosis` and `diagnosis-start` set only for new case findings | forced `react` | router verdict; a dx workflow on a voice turn is forced to `react` | forced `react` | | First-tool rules | R1, R1b, R2, R3, R4, R5 (see §3) | same, with a case marker | same | same | | Pinned tools | `ui_control`, `render_card`, `request_plan` | same | `voice_ui_control` in place of `ui_control`, plus `render_card`, `request_plan` | same as voice | | dx tools | ranked in, never pinned | ranked in, category `diagnosis` first | ranked in | ranked in, category `diagnosis` first | | Tool-RAG | up to 4 searched + up to 3 pinned | same caps; `preferCategory: "diagnosis"` | same caps | same caps; `preferCategory: "diagnosis"` | | MCP servers | the owner's MCP and plugin tools, up to 2 of the searched slots | same | same | same | | Skills | `pickTurnSkills`: up to 2 user skills by keyword, shared 600-token layer, plus plugin instructions | same | same | same | | Case scope source | none; `dx_case_find` or `dx_case_create` supplies one | `[case:<id>]` marker in the text | none unless bound | ticket binding, then the loopback scope frame | | Case directory | `dxDirectory` added by ddx-api to the forwarded body | same | scope frame carries it | scope frame carries it | Rows are written from `engine/turn-runner.ts`, `lanes/react/index.ts`, `lanes/react/dx-first-tool.ts`, `voice/turn-body.ts`, `tools/catalogue/index.ts`, `tools/kernel/tool-search.ts`, `customize/skills.ts` and `ddx-api/src/osprey/osprey-voice-ticket.service.ts` (all under `ddx-osprey-engine/src/` except the last). ## 2. Where the case scope comes from - **Typed.** The web text starts with `[case:<id>]`. The engine reads the marker (`CASE_MARKER`) and re-checks tenant and user ownership in every dx tool. ddx-api adds `dxDirectory` (the cases) and `dxProjects` (the readable projects with their groups, plus the groups that sit in no project) to the forwarded turn body. A browser value for either is never accepted. The same two keys ride a resume body and the voice scope frame. - **Case-bound voice.** ddx-api mints the voice ticket. A case id on the mint request is checked then through the kernel list scope. A readable case rides the ticket binding. An unreadable, foreign or unknown case is dropped and the ticket is minted unbound: one answer for all three, never a 403, so the mint reveals nothing. - **Scope frame.** ddx-api sends one `scope` text frame first on the engine socket (header `x-osprey-voice-scope: 1`). The engine requires it as the first frame; a second, a late or a malformed one closes the stream. ddx-api drops any `scope` frame that comes from the browser. The frame is trusted for which case, never for who the caller is. - **Voice turn body.** `voiceTurnBody` builds the typed case turn: marker, Dx persona, `noAgent`, server directory. The directory rides a request-only body key; it never reaches `osprey.event`, a prompt or a log. ## 3. First-tool rules (case-bound or not) Rules run in order; the first match wins. Source: header of `lanes/react/dx-first-tool.ts`. | Rule | When | Result | |---|---|---| | R0 | resume open (approve, deny, data) | nothing forced, nothing prefetched | | R1 | deep-content workflow | forces `start_deep_content` | | R2 | marked owned run | prefetches `dx_run_status` | | R1b | the turn names a case number (`DX-YYYY-NNNNN`, spoken forms too) | prefetches `dx_case_find` | | R3 | dx workflow with no `[case:]` marker | forces `dx_case_create`, never a memory answer | | R4 | `diagnosis-start` | ready draft forces `dx_run_start`; existing run prefetches `dx_run_status` | | R5 | `diagnosis` with a case | forces `dx_case_extract`; a case with a run prefetches `dx_run_status` first | | R6 | any other case turn | state note only | `dx_case_create` refuses when the specialty is not active. A card question routes with workflow `none` and stays free: it consults the disease cards (`dx_knowledge_search`, `dx_knowledge_read`). ## 4. Settings that bound a turn | Key | Seed | Effect | |---|---|---| | `assistant.react.maxSteps` | 8 | step bound of one react run | | `assistant.react.sameToolMax` | 2 | calls of one tool before the next is refused with an answer-now result | | `assistant.agent.defaultId` | – | agent of a typed turn with none picked | | `assistant.persona.defaultId` | – | persona when the body and session name none | | `assistant.memory.enabled` | – | off = no working memory or semantic recall | | `module.diagnosis.crossCaseRecall`, `crossCaseRecallTopK`, `recallLastMessages` | registry | recall for a case turn | The outcome-loop and eval keys are listed in `settings.md` (eleven keys added by this plan). ## 4a. Casework tools and the state gate Tools added by plan `osprey-assistant-casework`: `dx_case_open`, `dx_case_status`, `dx_report_pdf`, `dx_card_retire`, `dx_proposal_list`, `dx_proposal_review`, `dx_project_list`, `dx_project_read`, `dx_group_assign`, `dx_group_create`. | Permission | Holders | Tools | |---|---|---| | `diagnosis:write` | org-admin, staff | `dx_case_status`, `dx_group_assign`, `dx_group_create` | | `diagnosis:propose` | org-admin, staff | the card write tools | | `diagnosis:review` | exposure only: a platform super-admin, never role-mapped | `dx_proposal_list`, `dx_proposal_review` (read-only review chat; the decision stays in the web review) | Every tool that changes data has `requireApproval`: the doctor clicks the card, then the web applies the change through the BFF. Role decides who sees a tool. The state gate decides whether the case state allows it (`lanes/react/dx-tool-gate.ts`, a hard filter before the tool slots; the dropped reason is `state:<rule>`): | Row | Rule | Blocks | |---|---|---| | G1 | `answer-needs-waiting-run` | `dx_answer` unless a run waits for answers | | G2 | `start-needs-no-live-run` | a start tool while a run is queued or running | | G3 | `start-needs-ready-draft` | a start tool without a ready, unconfirmed draft | | G4 | `case-status-needs-case` | `dx_case_status` without a bound case | | G5 | `case-patch-needs-case` | `dx_case_patch` without a bound case | | G6 | `case-patch-needs-completed-run` | `dx_case_patch` without a completed run | | G7 | `result-needs-completed-run` | what-if, case report, report PDF, outputs without a completed run | | G8 | `create-needs-no-case` | `dx_case_create` when a case is already open | `dxProposalSpent`: the proposal tools (`dx_case_status`, `dx_case_create`, `dx_group_assign`, `dx_group_create`) run once per turn and never when a turn resumes after approve or deny. The answers route also carries the question round: a stale round gives 409 `DX_ANSWER_ROUND_STALE`, a round already taken gives 409 `DX_ANSWER_ROUND_TAKEN`. ## 4b. Safety override - **One path.** A doctor clicks the acknowledge form on the safety card (web, BFF, ddx-api, engine). No model tool, voice phrase or MCP call can make an override. The route is `POST /diagnosis/runs/:id/safety-override`; the engine needs the query `byDisplay` (the doctor label, never a user id), the read (`GET`) needs none. - **ddx-api relay.** POST for org-admin and staff only. The reason must reach `module.diagnosis.safetyOverrideReasonMin` characters. ddx-api reads the label server-side, relays, then writes one audit row (tried twice). - **Display only.** The override releases held guidance for display. A verdict and a score never change. - **Cover rule.** The stored override covers a run only while the round and the verdict match and every fired red flag is acknowledged. A re-scored run needs a new acknowledgement, which replaces the row. An empty acknowledgement is valid on a run with no fired red flag. - **Trail.** Every accepted acknowledgement is one append-only history row. That table is the authoritative trail. - **Read side.** Chat reads of a blocked run (knowledge, literature, cards) answer again while an override covers the run, with a warning rule the model must state first. The web shows an override banner and hides guidance with `isGuidanceWithheld`. The case report prints the override. - SQL: `042` (override, held guidance, answered round, retired cards), `043` (`by_display`), `044` (history, `round`). ## 4c. Blocks the Assistant shows Nine casework block kinds, ids only: `dx_run`, `dx_safety`, `dx_card`, `dx_case`, `dx_project`, `dx_report_pdf`, `dx_case_status`, `dx_group_change`, `dx_proposal_review` (the last shows the proposal review card of a pending card proposal). The `dx_questions` block carries the round. The run, question and scorecard cards share one record-binding hook. Texts live in the web namespace `diagnosis-casework`. ## 5. Known limits - Voice number resolution: a case number spoken in words resolves through `DX_CASE_NUMBER_LOOSE` forms only. A form the pattern does not cover reaches the model as plain text and the model must ask again. - An approval-gated tool past `sameToolMax` still shows its approval card and is refused at run time. - Model drift is seen in walks: the model can echo a refused code or announce a draft before the card exists. The prompts and tool replies bound it; they do not remove it. - The browser never reaches the engine; every hop above goes through the BFF and ddx-api. - Open findings of the casework walk (plan task 043), not fixed: - Card work: a retire request can pick `dx_card_propose`. The reviewer has no Assistant page, so the proposal review card cannot be reached there. - Voice: a case-bound voice turn is heard but gave no spoken answer. Answer-by-voice and open-report-by-voice are not walked. - Projects: "list projects" gave no answer; create group in a project and list cases by project are not walked. - The nine older write tools carry no permission (owner decision). - A reviewer who is the proposer gets a plain 400 with no code; the web matches the message text. --- Last reconciled: 2026-11-18 · plan osprey-assistant-casework task 044 ## Fix round 2026-11-18 (plan osprey-assistant-casework) - Reviewer access: the platform super-admin works in the portal role area `public`. The Assistant item is `platformOnly` there (`portal-registry.ts`): the nav hides it and the page gate refuses it for org-admins, who share the area. The web reads the fact from the org overview (`me.platformRole`). `diagnosis:review` is still added per turn for a platform super-admin only. - Reply guarantee: a react turn keeps `assistant.react.replyReserveSeconds` (seed 20) of its `assistant.react.timeBudgetSeconds` (seed 50) for the text reply; the reply nudge is the last prompt line of a reply step. - A blank list filter means no filter (`dx_project_list`, `dx_case_list`). - A retire ask goes to `dx_card_retire`; `dx_card_propose` refuses a root-path op before the approval card. - Card search reads Qdrant `osprey_dx_knowledge_v3`; an empty collection answers 0 cards. The reconcile job, `osprey dx index reconcile` and `osprey dx index rebuild` now fill it; `osprey dx doctor` row `index-drift` reports it as `cards(v3)`.
One map of what the assistant turn is made of, for the four turns a doctor can start: typed, case-bound typed,
voice, case-bound voice. Written from the merged code (plans osprey-assistant-engine and osprey-assistant-casework); code beats this page.
Glossary: CONTEXT.md. Engine overview: osprey-engine.md. Settings: settings.md.
The assistant never writes a kernel case. dx_case_create is a proposal: the engine emits an approval-gated
card, the web card creates the case through the BFF, then binds the chat (?case=).
Rows are written from engine/turn-runner.ts, lanes/react/index.ts, lanes/react/dx-first-tool.ts,
voice/turn-body.ts, tools/catalogue/index.ts, tools/kernel/tool-search.ts, customize/skills.ts and
ddx-api/src/osprey/osprey-voice-ticket.service.ts (all under ddx-osprey-engine/src/ except the last).
[case:<id>]. The engine reads the marker (CASE_MARKER) and re-checks
tenant and user ownership in every dx tool. ddx-api adds dxDirectory (the cases) and dxProjects (the readable projects with their
groups, plus the groups that sit in no project) to the forwarded turn body. A browser value for either is never
accepted. The same two keys ride a resume body and the voice scope frame.scope text frame first on the engine socket (header x-osprey-voice-scope: 1).
The engine requires it as the first frame; a second, a late or a malformed one closes the stream. ddx-api drops
any scope frame that comes from the browser. The frame is trusted for which case, never for who the caller is.voiceTurnBody builds the typed case turn: marker, Dx persona, noAgent, server directory.
The directory rides a request-only body key; it never reaches osprey.event, a prompt or a log.Rules run in order; the first match wins. Source: header of lanes/react/dx-first-tool.ts.
dx_case_create refuses when the specialty is not active. A card question routes with workflow none and stays
free: it consults the disease cards (dx_knowledge_search, dx_knowledge_read).
The outcome-loop and eval keys are listed in settings.md (eleven keys added by this plan).
Tools added by plan osprey-assistant-casework: dx_case_open, dx_case_status, dx_report_pdf, dx_card_retire,
dx_proposal_list, dx_proposal_review, dx_project_list, dx_project_read, dx_group_assign, dx_group_create.
Every tool that changes data has requireApproval: the doctor clicks the card, then the web applies the change
through the BFF. Role decides who sees a tool. The state gate decides whether the case state allows it
(lanes/react/dx-tool-gate.ts, a hard filter before the tool slots; the dropped reason is state:<rule>):
dxProposalSpent: the proposal tools (dx_case_status, dx_case_create, dx_group_assign, dx_group_create) run
once per turn and never when a turn resumes after approve or deny. The answers route also carries the question round:
a stale round gives 409 DX_ANSWER_ROUND_STALE, a round already taken gives 409 DX_ANSWER_ROUND_TAKEN.
POST /diagnosis/runs/:id/safety-override; the engine
needs the query byDisplay (the doctor label, never a user id), the read (GET) needs none.module.diagnosis.safetyOverrideReasonMin
characters. ddx-api reads the label server-side, relays, then writes one audit row (tried twice).isGuidanceWithheld. The case report prints the override.042 (override, held guidance, answered round, retired cards), 043 (by_display), 044 (history, round).Nine casework block kinds, ids only: dx_run, dx_safety, dx_card, dx_case, dx_project, dx_report_pdf,
dx_case_status, dx_group_change, dx_proposal_review (the last shows the proposal review card of a pending card
proposal). The dx_questions block carries the round. The run, question and scorecard cards share one record-binding
hook. Texts live in the web namespace diagnosis-casework.
DX_CASE_NUMBER_LOOSE forms only. A form
the pattern does not cover reaches the model as plain text and the model must ask again.sameToolMax still shows its approval card and is refused at run time.dx_card_propose. The reviewer has no Assistant page, so the proposal review
card cannot be reached there.Last reconciled: 2026-11-18 · plan osprey-assistant-casework task 044
public. The Assistant item is platformOnly there (portal-registry.ts): the nav hides it and the page gate refuses it for org-admins, who share the area. The web reads the fact from the org overview (me.platformRole). diagnosis:review is still added per turn for a platform super-admin only.assistant.react.replyReserveSeconds (seed 20) of its assistant.react.timeBudgetSeconds (seed 50) for the text reply; the reply nudge is the last prompt line of a reply step.dx_project_list, dx_case_list).dx_card_retire; dx_card_propose refuses a root-path op before the approval card.osprey_dx_knowledge_v3; an empty collection answers 0 cards. The reconcile job, osprey dx index reconcile and osprey dx index rebuild now fill it; osprey dx doctor row index-drift reports it as cards(v3).adr/
deploy/
research/