Skip to content

feat(types): add clinic inbox, outbox, and MCP result contracts #36

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
abrichr merged 1 commit into from
Sep 1, 2026
Merged

feat(types): add clinic inbox, outbox, and MCP result contracts #36

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,9 @@ out the pixels. Coordinates are the thing that breaks when a window moves.
| `AuthoringObserveV1` | PHI-safe authoring observe tree for the hosted MCP wire |
| `AuthoringCommandV1` | Mailbox envelope. Hosted click is `node_id` only; compile is `needs_human_admit` |
| `AuthoringBindV1` | Bind status plus exact `oab_` / `oals_` parsers. No tree, tokens, or secrets |
| `ClinicInboxV1` | Workbench job: opaque `patient_token`, artifact path, source, time |
| `ClinicOutboxV1` | Actuation intent. `needs_human: true` does not dispatch |
| `ClinicToolResultV1` | MCP result: `VERIFIED`, `HALTED`, or `RECONCILIATION_REQUIRED`. Halt is not success |

Plus the versioned wire contracts: `ControlOverlayFrameV1`/`V2` and
`ControlOverlayTimelineV1`/`V2` for PHI-safe execution overlays,
Expand All @@ -98,7 +101,7 @@ print(json.dumps(ComputerState.model_json_schema(), indent=2))
```

The same schemas ship as JSON under `openadapt_types/schemas/` for TypeScript,
Rust, and anything else that isn't Python. Twenty-seven files, including
Rust, and anything else that isn't Python. Thirty-one files, including
`execute-v1-openapi.json`, the public OpenAdapt Execute contract.

## Converting from the older formats
Expand Down
23 changes: 23 additions & 0 deletions docs/CONTRACTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,3 +140,26 @@ is `{ node_id }` only. Pause results name a param and never a value.
Compile returns `needs_human_admit`, never `VERIFIED`. Bind tokens are
`oab_` plus 43 unreserved characters. Lease secrets are `oals_` plus 64
hex characters. Cloud `oar_` and pairing `oap_` are refused.

## Clinic job inbox and MCP tools

`ClinicInboxV1`, `ClinicOutboxV1`, and `ClinicToolResultV1` are the public
handoff for a compiled clinic program. They are not a workbench. Schema
packs, extraction, review UI, NL2SQL, and OCR do not belong on this wire.

Inbox fields are `patient_token`, `artifact_path`, `source`, and
`recorded_at`. Identity is the opaque token. A name, MRN, screenshot, or
OCR string has no field. `artifact_path` is a relative POSIX path of
opaque segments; a live filename that could carry a person name is
refused.

Outbox fields are `action`, `template`, and `needs_human`. `template` is
an opaque id of a clinic-defined template, not the typed body. When
`needs_human` is true, `require_actuation_dispatch` refuses. OpenAdapt
types the template only after a human stamp.

The admitted MCP names are `run_harvest`, `run_attach_fax`, and
`run_create_triage_task`. Each returns `VERIFIED`, `HALTED`, or
`RECONCILIATION_REQUIRED`. `is_verified_success` is true only for
`VERIFIED`. There is no success flag a caller can set to launder a halt.
There is no tool that decides urgency or writes follow-up copy.
65 changes: 65 additions & 0 deletions openadapt_types/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,39 @@
parse_authoring_lease_secret,
parse_authoring_runner_uri,
)
from openadapt_types.clinic_job import (
ACTION_TO_TOOL,
CLINIC_INBOX_SCHEMA,
CLINIC_MCP_TOOL_CATALOG,
CLINIC_MCP_TOOL_DESCRIPTIONS,
CLINIC_MCP_TOOL_NAMES,
CLINIC_MCP_TOOLS_SCHEMA,
CLINIC_OUTBOX_SCHEMA,
CLINIC_TOOL_RESULT_SCHEMA,
TOOL_TO_ACTION,
ClinicActuationDecisionV1,
ClinicActuationHeld,
ClinicBoundToolCallV1,
ClinicInboxV1,
ClinicMcpToolCatalogV1,
ClinicMcpToolNameV1,
ClinicMcpToolSpecV1,
ClinicOutboxActionV1,
ClinicOutboxV1,
ClinicToolResultV1,
ClinicToolStatusV1,
ClinicToolUnknown,
bind_clinic_tool_call,
bind_clinic_tool_result,
clinic_mcp_tool_spec,
decide_actuation,
is_verified_success,
parse_clinic_inbox,
parse_clinic_outbox,
planner_status,
planner_visible_payload,
require_actuation_dispatch,
)
from openadapt_types.benchmark import (
BenchmarkAction,
BenchmarkAgent,
Expand Down Expand Up @@ -375,6 +408,38 @@
"parse_authoring_bind_token",
"parse_authoring_lease_secret",
"parse_authoring_runner_uri",
# clinic job inbox / outbox / MCP
"ACTION_TO_TOOL",
"CLINIC_INBOX_SCHEMA",
"CLINIC_MCP_TOOL_CATALOG",
"CLINIC_MCP_TOOL_DESCRIPTIONS",
"CLINIC_MCP_TOOL_NAMES",
"CLINIC_MCP_TOOLS_SCHEMA",
"CLINIC_OUTBOX_SCHEMA",
"CLINIC_TOOL_RESULT_SCHEMA",
"TOOL_TO_ACTION",
"ClinicActuationDecisionV1",
"ClinicActuationHeld",
"ClinicBoundToolCallV1",
"ClinicInboxV1",
"ClinicMcpToolCatalogV1",
"ClinicMcpToolNameV1",
"ClinicMcpToolSpecV1",
"ClinicOutboxActionV1",
"ClinicOutboxV1",
"ClinicToolResultV1",
"ClinicToolStatusV1",
"ClinicToolUnknown",
"bind_clinic_tool_call",
"bind_clinic_tool_result",
"clinic_mcp_tool_spec",
"decide_actuation",
"is_verified_success",
"parse_clinic_inbox",
"parse_clinic_outbox",
"planner_status",
"planner_visible_payload",
"require_actuation_dispatch",
# control_overlay
"CONTROL_OVERLAY_FRAME_SCHEMA",
"CONTROL_OVERLAY_STATE_ID_COMPONENTS",
Expand Down
Loading
Loading