@taco-ai/pi-harness 0.0.0-stage → 0.1.0

package/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.

package/package.json

@@ -1,6 +1,100 @@
 {
-  "name": "@taco-ai/pi-harness",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@taco-ai/pi-harness",
+	"version": "0.1.0",
+	"description": "AgentHarness extracted from @earendil-works/pi-agent-core@0.99.2, kept compatible with the latest pi base packages (pi-ai/chord/pi-telemetry 1.x)",
+	"author": "NiumAgents <niuma1024@outlook.com>",
+	"type": "module",
+	"packageManager": "pnpm@11.7.0",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./node": {
+			"types": "./dist/node.d.ts",
+			"import": "./dist/node.js"
+		},
+		"./harness/context": {
+			"types": "./dist/harness/context.d.ts",
+			"import": "./dist/harness/context.js"
+		},
+		"./experimental/pico3": {
+			"types": "./dist/harness/pico3/index.d.ts",
+			"import": "./dist/harness/pico3/index.js"
+		},
+		"./harness/env/nodejs": {
+			"types": "./dist/harness/env/nodejs.d.ts",
+			"import": "./dist/harness/env/nodejs.js"
+		},
+		"./harness/runtime/reducer": {
+			"types": "./dist/harness/runtime/reducer.d.ts",
+			"import": "./dist/harness/runtime/reducer.js"
+		},
+		"./harness/session": {
+			"types": "./dist/harness/session/index.d.ts",
+			"import": "./dist/harness/session/index.js"
+		},
+		"./harness/session/testing": {
+			"types": "./dist/harness/session/testing/index.d.ts",
+			"import": "./dist/harness/session/testing/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"files": [
+		"dist",
+		"docs",
+		"LICENSE",
+		"LICENSE.upstream",
+		"README.md",
+		"README.zh-CN.md"
+	],
+	"scripts": {
+		"clean": "shx rm -rf dist",
+		"build": "tsc -p tsconfig.build.json",
+		"docs:telemetry": "node --experimental-strip-types scripts/generate-telemetry-docs.ts",
+		"docs:telemetry:check": "node --experimental-strip-types scripts/generate-telemetry-docs.ts --check",
+		"test": "vitest --run",
+		"test:harness": "vitest --run --config vitest.harness.config.ts",
+		"test:session:conformance": "vitest --run --config vitest.harness.config.ts test/harness/memory-conformance.test.ts",
+		"typecheck": "tsc --noEmit",
+		"prepublishOnly": "npm run clean && npm run build && npm test"
+	},
+	"peerDependencies": {
+		"@earendil-works/chord": "^1.3.0",
+		"@earendil-works/pi-ai": "^1.3.0",
+		"@earendil-works/pi-telemetry": "^1.3.0"
+	},
+	"dependencies": {
+		"diff": "8.0.4",
+		"ignore": "7.0.8",
+		"typebox": "1.3.27",
+		"yaml": "2.9.0"
+	},
+	"devDependencies": {
+		"@types/node": "22.19.19",
+		"@vitest/coverage-v8": "4.1.11",
+		"shx": "0.4.0",
+		"typescript": "7.0.2",
+		"vitest": "4.1.11"
+	},
+	"keywords": [
+		"ai",
+		"agent",
+		"harness",
+		"llm",
+		"agentharness"
+	],
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "github:niuma996/pi-harness"
+	},
+	"engines": {
+		"node": ">=22.19.0"
+	}
+}