Patch history and file view API

Patch history lets clients inspect filesystem changes without treating a provider’s last event as an exact record. The gateway reports authority, provenance, exactness, coverage, and filesystem observation state with every history view. See Patch history and file mutation for the native mutation and recovery model.

Methods

Method	Params	Result	Purpose
`thread/patch_steps/page`	`ThreadPatchStepsPageParams`	`ThreadPatchStepsPageResponse`	Page applied patch steps across the visible thread execution scope.
`thread/file_patch_history/page`	`ThreadFilePatchHistoryPageParams`	`ThreadFilePatchHistoryPageResponse`	Page changes to one path across the visible thread execution scope.
`turn/patch_steps/page`	`TurnPatchStepsPageParams`	`TurnPatchStepsPageResponse`	Page native or provider-reported patch steps for one turn.
`turn/patch_record/get`	`TurnPatchRecordGetParams`	`TurnPatchRecordGetResponse`	Load one selected durable patch record.
`turn/patch_diff/get`	`TurnPatchDiffGetParams`	`TurnPatchDiffGetResponse`	Render a bounded unified diff for one turn and selection.
`thread/file/view_grant/create`	`ThreadFileViewGrantCreateParams`	`ThreadFileViewGrantCreateResponse`	Create a short-lived HTTP view URL for an authorized workspace text file.

Patch history reads are authorized against the source thread, turn, execution scope, and resolved workspace path. The gateway limits page records, compressed and decompressed bytes, and diff bytes.

Coverage fields

PatchHistoryQueryCoverage contains:

Field	Values
`exactness`	`engine_verified`, `provider_reported`, or `incomplete`.
`exact`	`true` only when the selected view is exact.
`coverage`	`engine_verified_steps`, `provider_reported_steps`, `aggregate_only`, `incomplete`, or `untracked`.
`filesystem`	`pending`, `complete`, or `incomplete`.
`first_missing_ordinal`	Optional first missing commit ordinal.

Use these fields when labeling a diff. A provider aggregate can be useful while still being less exact than a native engine record.

History views

The view field identifies timeline, turn_aggregate, or record_diff. A thread file history entry includes its source execution context, environment id, turn id, invocation id, ordinal, and one file change. A turn step includes the full record and coverage for that query. Cursors are opaque protocol objects. Thread file cursors contain environment, turn, ordinal, sequence, source thread, and commit timestamp fields. Restart pagination without a cursor when the cursor lacks the source thread or commit time required by the current scope.

Patch record and diff selection

Patch records expose authority, provenance, exactness, outcome, content-addressed before and after snapshots, change kind, source and destination paths, and side effects. Change kinds are add, replace, update, delete, and move. turn/patch_record/get accepts a typed selector for a turn record. turn/patch_diff/get accepts a selection and an optional max_bytes, capped by the gateway. The response contains the exactness, coverage, filesystem status, unified patch, rendered record count, and the ordinal range represented by the diff.

File view grant

The file viewer does not receive a raw path and read it locally. A client sends the thread, optional turn and item context, and the markdown link href to thread/file/view_grant/create:

{
  "method": "thread/file/view_grant/create",
  "params": {
    "threadId": "thr_000000000000000001",
    "turnId": "trn_000000000000000001",
    "itemId": "itm_000000000000000001",
    "href": "src/main.rs:42"
  }
}

The response contains a relative /storage/views/... URL, expiry, file name, content type, byte size, and optional line and column. The gateway resolves and authorizes the workspace path. Text files are bounded to 10 MiB and are not silently truncated. The client uses the relative URL with the authenticated gateway base URL. The grant is short lived and tied to the session and resolved file scope. A browser or system viewer receives only this grant URL, not a durable bearer credential.

Turns API explains turn work and permission admission.
Threads API explains thread authorization and timeline reads.
Artifacts API covers durable uploaded files, which use a different storage identity.
Authentication and access API explains session and capability checks.

Generated schemas

The coverage, step, and file-history types are nested in the response schemas and are not emitted as standalone files. The generated method schemas are:

/schemas/thread_patch_steps_page_params.json
/schemas/thread_patch_steps_page_response.json
/schemas/thread_file_patch_history_page_params.json
/schemas/thread_file_patch_history_page_response.json
/schemas/turn_patch_steps_page_params.json
/schemas/turn_patch_steps_page_response.json
/schemas/turn_patch_record_get_params.json
/schemas/turn_patch_record_get_response.json
/schemas/turn_patch_diff_get_params.json
/schemas/turn_patch_diff_get_response.json
/schemas/thread_file_view_grant_create_params.json
/schemas/thread_file_view_grant_create_response.json

Introduction

Workspace & Threads

Features

Patch history and file view API

Methods

Coverage fields

History views

Patch record and diff selection

File view grant

Generated schemas

​Methods

​Coverage fields

​History views

​Patch record and diff selection

​File view grant

​Related protocol surfaces

​Generated schemas

Methods

Coverage fields

History views

Patch record and diff selection

File view grant

Related protocol surfaces

Generated schemas