Skip to content

feat(types): authoring observe, command, and bind schemas #35

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 2 commits into from
Sep 1, 2026
Merged

feat(types): authoring observe, command, and bind schemas #35

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3abf298
feat(types): authoring observe, command, and bind schemas
abrichr Aug 31, 2026
46d08e4
feat(types): close remaining authoring MCP wire holes
abrichr Sep 1, 2026
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 @@ -74,6 +74,9 @@ out the pixels. Coordinates are the thing that breaks when a window moves.
| `CodeCapabilityManifestV1` | Exact Python, locked dependencies, typed I/O, permissions, and verifier bindings |
| `ProcessEvidenceReceiptV1` | One signed root over child receipts, human receipts, and the artifact graph |
| `AuthenticationTaskContractV1` | A value-free login requirement bound to an existing attended task |
| `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 |

Plus the versioned wire contracts: `ControlOverlayFrameV1`/`V2` and
`ControlOverlayTimelineV1`/`V2` for PHI-safe execution overlays,
Expand All @@ -95,7 +98,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-four files, including
Rust, and anything else that isn't Python. Twenty-seven files, including
`execute-v1-openapi.json`, the public OpenAdapt Execute contract.

## Converting from the older formats
Expand Down
19 changes: 19 additions & 0 deletions docs/CONTRACTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,3 +121,22 @@ freshness rule, user-presence result, MFA result, and verifier result agrees.
This is a wire contract, not a complete authentication feature. Capture,
Flow, and the operator surface must share the protected interval before a
release can claim the complete path.

## Authoring MCP wire

`AuthoringObserveV1`, `AuthoringCommandV1`, and `AuthoringBindV1` are the
public hosted-authoring contracts. They do not reuse `ComputerState` or
`UINode`. Sharing `ElementRole` is the only computer-state type on this
wire. The projector that drops field values, titles, and screenshots lives
in Capture. These models refuse those keys.

Observe is a PHI-safe projected tree: roles, automation ids, normalized
bounds, and `node_id`. It does not carry `value`, `title`, `screenshot`,
`text`, window titles, URLs, backend pixels, or extra keys. Cap is 200
nodes and 32 KiB. Windows native, RDP, and Citrix are `coach_only`.

The mailbox envelope is `openadapt.authoring.command/v1`. Hosted `click`
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.
113 changes: 113 additions & 0 deletions openadapt_types/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,63 @@
ActionTarget,
ActionType,
)
from openadapt_types.authoring import (
AUTHORING_BIND_SCHEMA,
AUTHORING_COMMAND_SCHEMA,
AUTHORING_MAX_COMMAND_BYTES,
AUTHORING_MAX_OBSERVE_BYTES,
AUTHORING_OBSERVE_SCHEMA,
BIND_SCHEMA_VERSION,
COMMAND_SCHEMA_VERSION,
OBSERVE_SCHEMA_VERSION,
AuthoringAllowStateV1,
AuthoringBackendV1,
AuthoringBindClaimV1,
AuthoringBindMintV1,
AuthoringBindPackArgsV1,
AuthoringBindPackResultV1,
AuthoringBindV1,
AuthoringCallbackV1,
AuthoringClickArgsV1,
AuthoringClickResultV1,
AuthoringClientDisplayV1,
AuthoringCommandLookupArgsV1,
AuthoringCommandLookupV1,
AuthoringCommandStatusV1,
AuthoringCommandV1,
AuthoringCompileResultV1,
AuthoringEmptyProjectionReason,
AuthoringEnqueueAcceptedV1,
AuthoringEnqueueToolV1,
AuthoringErrorCodeV1,
AuthoringErrorResultV1,
AuthoringGetCoachResultV1,
AuthoringHaltResultV1,
AuthoringHostedClickArgsV1,
AuthoringHostedPackArgsV1,
AuthoringHostedPauseArgsV1,
AuthoringHostedSetCoachArgsV1,
AuthoringInFlightV1,
AuthoringNodeV1,
AuthoringNormalizedBoundsV1,
AuthoringNotBoundV1,
AuthoringObserveV1,
AuthoringPauseArgsV1,
AuthoringPauseResultV1,
AuthoringPollRequestV1,
AuthoringProviderV1,
AuthoringRecordingResultV1,
AuthoringRunnerUriV1,
AuthoringSetCoachArgsV1,
AuthoringSetCoachResultV1,
AuthoringTokenError,
AuthoringWindowV1,
BIND_TOKEN_PATTERN,
LEASE_SECRET_PATTERN,
parse_authoring_bind_token,
parse_authoring_lease_secret,
parse_authoring_runner_uri,
)
from openadapt_types.benchmark import (
BenchmarkAction,
BenchmarkAgent,
Expand Down Expand Up @@ -262,6 +319,62 @@
"ElementRole",
"ProcessInfo",
"UINode",
# authoring MCP wire
"AUTHORING_BIND_SCHEMA",
"AUTHORING_COMMAND_SCHEMA",
"AUTHORING_MAX_COMMAND_BYTES",
"AUTHORING_MAX_OBSERVE_BYTES",
"AUTHORING_OBSERVE_SCHEMA",
"BIND_SCHEMA_VERSION",
"COMMAND_SCHEMA_VERSION",
"OBSERVE_SCHEMA_VERSION",
"AuthoringAllowStateV1",
"AuthoringBackendV1",
"AuthoringBindClaimV1",
"AuthoringBindMintV1",
"AuthoringBindPackArgsV1",
"AuthoringBindPackResultV1",
"AuthoringBindV1",
"AuthoringCallbackV1",
"AuthoringClickArgsV1",
"AuthoringClickResultV1",
"AuthoringClientDisplayV1",
"AuthoringCommandLookupArgsV1",
"AuthoringCommandLookupV1",
"AuthoringCommandStatusV1",
"AuthoringCommandV1",
"AuthoringCompileResultV1",
"AuthoringEmptyProjectionReason",
"AuthoringEnqueueAcceptedV1",
"AuthoringEnqueueToolV1",
"AuthoringErrorCodeV1",
"AuthoringErrorResultV1",
"AuthoringGetCoachResultV1",
"AuthoringHaltResultV1",
"AuthoringHostedClickArgsV1",
"AuthoringHostedPackArgsV1",
"AuthoringHostedPauseArgsV1",
"AuthoringHostedSetCoachArgsV1",
"AuthoringInFlightV1",
"AuthoringNodeV1",
"AuthoringNormalizedBoundsV1",
"AuthoringNotBoundV1",
"AuthoringObserveV1",
"AuthoringPauseArgsV1",
"AuthoringPauseResultV1",
"AuthoringPollRequestV1",
"AuthoringProviderV1",
"AuthoringRecordingResultV1",
"AuthoringRunnerUriV1",
"AuthoringSetCoachArgsV1",
"AuthoringSetCoachResultV1",
"AuthoringTokenError",
"AuthoringWindowV1",
"BIND_TOKEN_PATTERN",
"LEASE_SECRET_PATTERN",
"parse_authoring_bind_token",
"parse_authoring_lease_secret",
"parse_authoring_runner_uri",
# control_overlay
"CONTROL_OVERLAY_FRAME_SCHEMA",
"CONTROL_OVERLAY_STATE_ID_COMPONENTS",
Expand Down
Loading
Loading