chore(vendor): import pi 0.85.1

Imported as a linear vendor commit so forge rebases do not replay the upstream root tree.

git-subtree-dir: third_party/pi

git-subtree-split: d981de1229ef899957bbe968bc8dcda02a21f477

third_party/pi/packages/agent/docs/telemetry-schema.md

@@ -0,0 +1,383 @@
+# Pi Agent Telemetry Schemas
+
+<!-- Generated by generate-telemetry-docs.ts. Do not edit manually. -->
+
+## AI request schema
+
+Schema version: 1
+
+### `pi.ai.request`
+
+One logical request to an AI provider
+
+- Parents: root or any caller span
+- Default status: `ok`
+- Error when: The operation throws or returns an error result
+
+#### Start attributes
+
+| Name | Type | Required | Values | Notes | Description |
+|---|---|---:|---|---|---|
+| `pi.ai.operation` | `string` | yes | stream, fetch_deferred, cancel_deferred, generate_images |  | Logical provider operation |
+| `pi.ai.provider` | `string` | yes |  |  | Selected provider id |
+| `pi.ai.model` | `string` | yes |  |  | Requested model id |
+| `pi.ai.api` | `string` | yes |  |  | Provider API id |
+| `pi.ai.streaming` | `boolean` | yes |  |  | Whether this operation returns a stream |
+| `pi.ai.deferred` | `boolean` | no |  |  | Whether the operation requests or participates in deferred execution |
+
+#### End attributes
+
+All end attributes are optional completion enrichment.
+
+| Name | Type | Values | Notes | Description |
+|---|---|---|---|---|
+| `pi.ai.response.model` | `string` |  |  | Concrete response model |
+| `pi.ai.response.id` | `string` |  | high cardinality | Provider response id |
+| `pi.ai.response.stop_reason` | `string` | stop, length, tool_use, error, aborted, deferred |  | Normalized terminal response reason |
+| `pi.ai.http.status_code` | `number` |  |  | Final HTTP status |
+| `pi.ai.usage.input_tokens` | `number` |  |  | Reported input tokens |
+| `pi.ai.usage.output_tokens` | `number` |  |  | Reported output tokens |
+| `pi.ai.usage.cache_read_tokens` | `number` |  |  | Reported cache-read tokens |
+| `pi.ai.usage.cache_write_tokens` | `number` |  |  | Reported cache-write tokens |
+| `pi.ai.usage.reasoning_tokens` | `number` |  |  | Reported reasoning tokens |
+| `pi.ai.usage.total_tokens` | `number` |  |  | Reported total tokens |
+| `pi.ai.usage.cost` | `number` |  |  | Reported total cost |
+| `pi.ai.stream.chunk_count` | `number` |  |  | Streamed update chunk count |
+| `pi.ai.stream.time_to_first_chunk_ms` | `number` |  |  | Elapsed milliseconds to first update chunk |
+| `pi.ai.error.type` | `string` |  | low cardinality | Provider or transport error class |
+
+#### Events
+
+No declared span events.
+
+## Harness schema
+
+Schema version: 1
+
+### `pi.harness.run`
+
+One admitted in-process run invocation
+
+- Parents: root or caller-owned external span
+- Default status: `ok`
+- Error when: The run fails or throws
+
+#### Start attributes
+
+| Name | Type | Required | Values | Notes | Description |
+|---|---|---:|---|---|---|
+| `pi.session.id` | `string` | yes |  | high cardinality | Session id |
+| `pi.lane.name` | `string` | yes |  | high cardinality | Lane name |
+| `pi.operation.id` | `string` | yes |  | high cardinality | Durable operation id |
+| `pi.operation.recovery` | `boolean` | yes |  |  | Whether this invocation resumes durable work |
+| `pi.operation.kind` | `string` | yes | run |  | Run operation kind |
+
+#### End attributes
+
+All end attributes are optional completion enrichment.
+
+| Name | Type | Values | Notes | Description |
+|---|---|---|---|---|
+| `pi.operation.outcome` | `string` | completed, aborted, failed, suspended |  | Run invocation outcome |
+| `pi.error.code` | `string` |  | low cardinality | Stable operation error code |
+| `pi.error.type` | `string` |  | low cardinality | Low-cardinality operation error class |
+
+#### Events
+
+No declared span events.
+
+### `pi.harness.compaction`
+
+One admitted in-process manual compaction invocation
+
+- Parents: root or caller-owned external span
+- Default status: `ok`
+- Error when: The compaction fails or throws
+
+#### Start attributes
+
+| Name | Type | Required | Values | Notes | Description |
+|---|---|---:|---|---|---|
+| `pi.session.id` | `string` | yes |  | high cardinality | Session id |
+| `pi.lane.name` | `string` | yes |  | high cardinality | Lane name |
+| `pi.operation.id` | `string` | yes |  | high cardinality | Durable operation id |
+| `pi.operation.recovery` | `boolean` | yes |  |  | Whether this invocation resumes durable work |
+| `pi.operation.kind` | `string` | yes | compaction |  | Compaction operation kind |
+
+#### End attributes
+
+All end attributes are optional completion enrichment.
+
+| Name | Type | Values | Notes | Description |
+|---|---|---|---|---|
+| `pi.operation.outcome` | `string` | completed, declined, aborted, failed |  | Compaction invocation outcome |
+| `pi.error.code` | `string` |  | low cardinality | Stable operation error code |
+| `pi.error.type` | `string` |  | low cardinality | Low-cardinality operation error class |
+
+#### Events
+
+No declared span events.
+
+### `pi.harness.navigation`
+
+One admitted in-process navigation invocation
+
+- Parents: root or caller-owned external span
+- Default status: `ok`
+- Error when: The navigation fails or throws
+
+#### Start attributes
+
+| Name | Type | Required | Values | Notes | Description |
+|---|---|---:|---|---|---|
+| `pi.session.id` | `string` | yes |  | high cardinality | Session id |
+| `pi.lane.name` | `string` | yes |  | high cardinality | Lane name |
+| `pi.operation.id` | `string` | yes |  | high cardinality | Durable operation id |
+| `pi.operation.recovery` | `boolean` | yes |  |  | Whether this invocation resumes durable work |
+| `pi.operation.kind` | `string` | yes | navigation |  | Navigation operation kind |
+
+#### End attributes
+
+All end attributes are optional completion enrichment.
+
+| Name | Type | Values | Notes | Description |
+|---|---|---|---|---|
+| `pi.operation.outcome` | `string` | completed, declined, aborted, failed |  | Navigation invocation outcome |
+| `pi.error.code` | `string` |  | low cardinality | Stable operation error code |
+| `pi.error.type` | `string` |  | low cardinality | Low-cardinality operation error class |
+
+#### Events
+
+No declared span events.
+
+### `pi.harness.checkpoint`
+
+One run checkpoint
+
+- Parents: `pi.harness.run`
+- Default status: `ok`
+- Error when: Checkpoint work throws
+
+#### Start attributes
+
+| Name | Type | Required | Values | Notes | Description |
+|---|---|---:|---|---|---|
+| `pi.lane.name` | `string` | yes |  | high cardinality | Lane name |
+| `pi.operation.id` | `string` | yes |  | high cardinality | Durable operation id |
+| `pi.checkpoint.kind` | `string` | yes | normal, abort_reconcile |  | Checkpoint purpose |
+
+#### End attributes
+
+All end attributes are optional completion enrichment.
+
+| Name | Type | Values | Notes | Description |
+|---|---|---|---|---|
+| _none_ | | | | |
+
+#### Events
+
+No declared span events.
+
+### `pi.harness.turn`
+
+One assistant response and its tool batch
+
+- Parents: `pi.harness.run`
+- Default status: `ok`
+- Error when: Turn work throws
+
+#### Start attributes
+
+| Name | Type | Required | Values | Notes | Description |
+|---|---|---:|---|---|---|
+| `pi.lane.name` | `string` | yes |  | high cardinality | Lane name |
+| `pi.operation.id` | `string` | yes |  | high cardinality | Durable operation id |
+| `pi.turn.id` | `string` | yes |  | high cardinality | Invocation-local turn id |
+
+#### End attributes
+
+All end attributes are optional completion enrichment.
+
+| Name | Type | Values | Notes | Description |
+|---|---|---|---|---|
+| _none_ | | | | |
+
+#### Events
+
+No declared span events.
+
+### `pi.harness.step`
+
+One durable retry attempt
+
+- Parents: `pi.harness.turn`, `pi.harness.checkpoint`, `pi.harness.compaction`, `pi.harness.navigation`
+- Default status: `ok`
+- Error when: The attempt retries, fails, or throws
+
+#### Start attributes
+
+| Name | Type | Required | Values | Notes | Description |
+|---|---|---:|---|---|---|
+| `pi.lane.name` | `string` | yes |  | high cardinality | Lane name |
+| `pi.operation.id` | `string` | yes |  | high cardinality | Durable operation id |
+| `pi.step.kind` | `string` | yes | assistant, compaction, branch_summary |  | Retryable step kind |
+| `pi.step.attempt` | `number` | yes |  |  | One-based durable attempt number |
+| `pi.compaction.reason` | `string` | no | manual, threshold, overflow |  | Compaction trigger |
+
+#### End attributes
+
+All end attributes are optional completion enrichment.
+
+| Name | Type | Values | Notes | Description |
+|---|---|---|---|---|
+| `pi.step.outcome` | `string` | succeeded, retry, failed, aborted, deferred, overflow |  | Attempt outcome |
+
+#### Events
+
+No declared span events.
+
+### `pi.harness.tool`
+
+One raw phase-2 tool execution
+
+- Parents: `pi.harness.turn`, `pi.harness.run`
+- Default status: `ok`
+- Error when: Raw phase-2 execution returns an error
+
+#### Start attributes
+
+| Name | Type | Required | Values | Notes | Description |
+|---|---|---:|---|---|---|
+| `pi.lane.name` | `string` | yes |  | high cardinality | Lane name |
+| `pi.operation.id` | `string` | yes |  | high cardinality | Durable operation id |
+| `pi.turn.id` | `string` | no |  | high cardinality | Invocation-local live turn id |
+| `pi.tool.name` | `string` | yes |  |  | Tool name |
+| `pi.tool.call_id` | `string` | yes |  | high cardinality | Tool call id |
+| `pi.tool.replay` | `string` | yes | never, safe |  | Declared replay policy |
+| `pi.tool.recovery` | `boolean` | yes |  |  | Whether this is recovery execution |
+
+#### End attributes
+
+All end attributes are optional completion enrichment.
+
+| Name | Type | Values | Notes | Description |
+|---|---|---|---|---|
+| `pi.tool.is_error` | `boolean` |  |  | Whether raw phase-2 execution returned an error |
+
+#### Events
+
+No declared span events.
+
+### `pi.harness.hook`
+
+One registered hook handler invocation
+
+- Parents: root or any caller span
+- Default status: `ok`
+- Error when: The handler throws
+
+#### Start attributes
+
+| Name | Type | Required | Values | Notes | Description |
+|---|---|---:|---|---|---|
+| `pi.lane.name` | `string` | yes |  | high cardinality | Lane name |
+| `pi.operation.id` | `string` | no |  | high cardinality | Durable operation id when accepted |
+| `pi.hook.name` | `string` | yes | before_run, before_drive, before_run_end, transform_context, before_request, before_payload, after_response, before_tool, after_tool, before_compaction, before_navigation |  | Hook name |
+| `pi.hook.registration_id` | `string` | no |  |  | Optional hook registration metadata |
+
+#### End attributes
+
+All end attributes are optional completion enrichment.
+
+| Name | Type | Values | Notes | Description |
+|---|---|---|---|---|
+| `pi.hook.outcome` | `string` | completed, skipped, blocked, failed |  | Handler outcome |
+
+#### Events
+
+No declared span events.
+
+### `pi.harness.sleep`
+
+One retry delay
+
+- Parents: `pi.harness.run`, `pi.harness.compaction`, `pi.harness.navigation`, `pi.harness.turn`, `pi.harness.checkpoint`
+- Default status: `ok`
+- Error when: Sleep work throws
+
+#### Start attributes
+
+| Name | Type | Required | Values | Notes | Description |
+|---|---|---:|---|---|---|
+| `pi.operation.id` | `string` | yes |  | high cardinality | Durable operation id |
+| `pi.sleep.delay_ms` | `number` | yes |  |  | Requested delay in milliseconds |
+
+#### End attributes
+
+All end attributes are optional completion enrichment.
+
+| Name | Type | Values | Notes | Description |
+|---|---|---|---|---|
+| `pi.sleep.outcome` | `string` | elapsed, aborted |  | Delay outcome |
+
+#### Events
+
+No declared span events.
+
+### `pi.harness.event_handler`
+
+One passive event listener invocation
+
+- Parents: root or any caller span
+- Default status: `ok`
+- Error when: The listener throws
+
+#### Start attributes
+
+| Name | Type | Required | Values | Notes | Description |
+|---|---|---:|---|---|---|
+| `pi.event.type` | `string` | yes | run_start, run_resume, run_suspend, operation_abort, run_end, fault, handler_error, turn_start, turn_end, retry_scheduled, retry_start, retry_end, message_start, message_update, message_end, tool_start, tool_update, tool_end, entry_added, queue_update, value_update, config_update, compaction_start, compaction_end, navigation_start, navigation_end, lane_created, usage | low cardinality | Delivered harness event type |
+| `pi.lane.name` | `string` | no |  | high cardinality | Lane name for lane-scoped events |
+
+#### End attributes
+
+All end attributes are optional completion enrichment.
+
+| Name | Type | Values | Notes | Description |
+|---|---|---|---|---|
+| _none_ | | | | |
+
+#### Events
+
+No declared span events.
+
+### `pi.session.write`
+
+One committed session transaction
+
+- Parents: root or any caller span
+- Default status: `ok`
+- Error when: Storage rejects the transaction
+
+#### Start attributes
+
+| Name | Type | Required | Values | Notes | Description |
+|---|---|---:|---|---|---|
+| `pi.session.id` | `string` | yes |  | high cardinality | Session id |
+| `pi.lane.name` | `string` | no |  | high cardinality | Lane name when supplied by the caller |
+| `pi.operation.id` | `string` | no |  | high cardinality | Durable operation id when supplied by the caller |
+| `pi.session.item_count` | `number` | yes |  |  | Number of writes in the transaction |
+| `pi.session.item_kinds` | `string[]` | yes | elements: entry, usage, value, list |  | Distinct write kinds in the transaction |
+
+#### End attributes
+
+All end attributes are optional completion enrichment.
+
+| Name | Type | Values | Notes | Description |
+|---|---|---|---|---|
+| `pi.session.first_seq` | `number` |  |  | First committed sequence in the transaction |
+| `pi.session.last_seq` | `number` |  |  | Last committed sequence in the transaction |
+
+#### Events
+
+No declared span events.