jademind-pi-telemetry

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# @jademind/pi-telemetry

> Migration: package moved from `pi-telemetry` to `@jademind/pi-telemetry`.

Structured runtime telemetry for `pi-coding-agent`, designed for external services (menu bar apps, daemons, web dashboards, alerting pipelines), including the free open-source macOS app [`pi-statusbar`](https://github.com/jademind/pi-statusbar).

`@jademind/pi-telemetry` publishes one JSON heartbeat file per running Pi process and ships a snapshot CLI to aggregate all active processes into a single machine-level payload.

---

## Highlights

- **Per-process telemetry heartbeat** (PID-scoped JSON files)
- **Session + model metadata** for each running Pi instance
- **Activity state** (`working`, `waiting_input`, `unknown`)
- **Context-window pressure metrics** (including near-limit detection)
- **External-service friendly snapshot** with aggregate + grouped maps
- **Atomic file writes** for robust consumers
- **No daemon required**: integrate by reading files or invoking snapshot CLI

---

## Installation

```bash
pi install npm:@jademind/pi-telemetry
```

The extension is auto-loaded through the package `pi.extensions` manifest.

---

## Runtime behavior

On key Pi lifecycle events (`session_start`, `turn_start`, `turn_end`, etc.), the extension writes/updates:

```text
~/.pi/agent/telemetry/instances/<pid>.json
```

On graceful shutdown (`session_shutdown`), the process file is removed.

### Configuration

Environment variables:

- `PI_TELEMETRY_DIR` (default: `~/.pi/agent/telemetry/instances`)
- `PI_TELEMETRY_HEARTBEAT_MS` (default: `1500`, minimum: `250`)
- `PI_TELEMETRY_CLOSE_PERCENT` (default: `85`)
- `PI_TELEMETRY_NEAR_PERCENT` (default: `95`)
- `PI_TELEMETRY_STALE_MS` (used by snapshot CLI; default: `10000`)

Inside Pi, use:

- `/pi-telemetry` to display the active telemetry file path.
- `/pi-telemetry --data` (or `--json`) to also print the latest per-process telemetry payload.
- Add `--pretty` for formatted JSON output.

---

## Snapshot CLI

Aggregate all live telemetry into one JSON document:

```bash
pi-telemetry-snapshot --pretty
```

### CLI options

- `--stale-ms <ms>`: stale threshold override
- `--pretty`: pretty-printed JSON output

### Exit behavior

- Returns JSON even when no instances exist (`counts.total = 0`)
- Skips invalid/corrupt JSON files

---

## Output schema

Top-level snapshot (`schemaVersion: 2`) includes:

- `aggregate`: `none | working | waiting_input | mixed`
- `counts`: totals by activity
- `context`: fleet-level context pressure summary
- `sessions`: map keyed by `session.id`
- `instancesByPid`: map keyed by string pid
- `instances`: ordered array of full active records

### Per-instance fields

- `process`: pid/ppid/uptime/heartbeat timestamps
- `system`: host/user/platform/arch/nodeVersion
- `workspace`: cwd + optional git branch/commit
- `session`: id/file/name
- `model`: provider/id/name/thinkingLevel (if available)
- `state`: activity and idleness flags
- `context`: token usage and pressure classification
- `routing`: jump-oriented metadata (tty, mux, mux session, terminal app hints, tmux pane target, zellij tab candidates/match when available)
- `capabilities`: currently `hasUI`
- `extensions`:
  - `telemetry`: extension presence (`@jademind/pi-telemetry`, always active when snapshot exists)
  - `bridge`: per-PID bridge activity (`@jademind/pi-bridge`) inferred from `~/.pi/agent/statusbridge/registry/<pid>.json` freshness
- `messages.lastAssistantText`: latest assistant response text when available via Pi API
- `messages.lastAssistantHtml`: HTML-safe rendering of latest assistant text (`<div class="pi-last-assistant"><pre>...</pre></div>`)
- `messages.lastAssistantUpdatedAt`: timestamp (ms) for latest assistant text capture
- `lastEvent`: most recent triggering Pi lifecycle event
- `telemetry`: snapshot-side metadata (`alive`, `stale`, `ageMs`, source file)

### Context pressure model

Derived from `context.percent`:

- `normal`
- `approaching_limit` (>= `PI_TELEMETRY_CLOSE_PERCENT`)
- `near_limit` (>= `PI_TELEMETRY_NEAR_PERCENT`)
- `at_limit` (>= `100`)

Additional booleans are provided for easy filtering:

- `closeToLimit`
- `nearLimit`

---

## Example integration

### macOS status bar app (open source / free)

- [`pi-statusbar`](https://github.com/jademind/pi-statusbar): a free macOS status bar application for Pi built on top of `pi-telemetry`.
- [`PiTalk`](https://github.com/swairshah/PiTalk): an additional open-source integration example using `pi-telemetry`.

### Poll from a daemon

```bash
pi-telemetry-snapshot | jq '.aggregate, .counts, .context'
```

### Get all sessions currently near context limit

```bash
pi-telemetry-snapshot | jq '
  .sessions
  | to_entries
  | map(select(.value.context.nearLimit > 0))
'
```

### Check whether any Pi is waiting for input

```bash
pi-telemetry-snapshot | jq '.counts.waiting_input > 0'
```

---

## Development

```bash
npm pack --dry-run
node ./bin/pi-telemetry-snapshot.mjs --pretty
```

Suggested release checklist:

1. Update version in `package.json`
2. Validate tarball with `npm pack --dry-run`
3. Verify CLI output in a live Pi session
4. Tag and publish

---

## Security model

- Telemetry is written to the local filesystem under your user account.
- Consumers should treat files as untrusted input and validate JSON.
- Snapshot CLI performs liveness/staleness filtering; downstream systems should still apply their own policy checks.

---

## OSS best practices

- Keep package references scoped (`@jademind/pi-telemetry`, `@jademind/pi-bridge`) in all docs/examples.
- Preserve backward compatibility in schema fields where possible; document additive vs breaking changes.
- Prefer atomic writes and bounded payload size to protect downstream readers.
- Keep release notes aligned across npm package, Git tag, and dependent integrations (status bar / mobile clients).

---

## License

MIT — see [LICENSE](https://github.com/jademind/pi-telemetry/tree/HEAD/LICENSE).

@jademind/pi-telemetry

Migration: package moved from pi-telemetry to @jademind/pi-telemetry.

Structured runtime telemetry for pi-coding-agent, designed for external services (menu bar apps, daemons, web dashboards, alerting pipelines), including the free open-source macOS app pi-statusbar.

@jademind/pi-telemetry publishes one JSON heartbeat file per running Pi process and ships a snapshot CLI to aggregate all active processes into a single machine-level payload.

Highlights

Per-process telemetry heartbeat (PID-scoped JSON files)
Session + model metadata for each running Pi instance
Activity state (working, waiting_input, unknown)
Context-window pressure metrics (including near-limit detection)
External-service friendly snapshot with aggregate + grouped maps
Atomic file writes for robust consumers
No daemon required: integrate by reading files or invoking snapshot CLI

Installation

pi install npm:@jademind/pi-telemetry

The extension is auto-loaded through the package pi.extensions manifest.

Runtime behavior

On key Pi lifecycle events (session_start, turn_start, turn_end, etc.), the extension writes/updates:

~/.pi/agent/telemetry/instances/<pid>.json

On graceful shutdown (session_shutdown), the process file is removed.

Configuration

Environment variables:

PI_TELEMETRY_DIR (default: ~/.pi/agent/telemetry/instances)
PI_TELEMETRY_HEARTBEAT_MS (default: 1500, minimum: 250)
PI_TELEMETRY_CLOSE_PERCENT (default: 85)
PI_TELEMETRY_NEAR_PERCENT (default: 95)
PI_TELEMETRY_STALE_MS (used by snapshot CLI; default: 10000)

Inside Pi, use:

/pi-telemetry to display the active telemetry file path.
/pi-telemetry --data (or --json) to also print the latest per-process telemetry payload.
Add --pretty for formatted JSON output.

Snapshot CLI

Aggregate all live telemetry into one JSON document:

pi-telemetry-snapshot --pretty

CLI options

--stale-ms <ms>: stale threshold override
--pretty: pretty-printed JSON output

Exit behavior

Returns JSON even when no instances exist (counts.total = 0)
Skips invalid/corrupt JSON files

Output schema

Top-level snapshot (schemaVersion: 2) includes:

aggregate: none | working | waiting_input | mixed
counts: totals by activity
context: fleet-level context pressure summary
sessions: map keyed by session.id
instancesByPid: map keyed by string pid
instances: ordered array of full active records

Per-instance fields

process: pid/ppid/uptime/heartbeat timestamps
system: host/user/platform/arch/nodeVersion
workspace: cwd + optional git branch/commit
session: id/file/name
model: provider/id/name/thinkingLevel (if available)
state: activity and idleness flags
context: token usage and pressure classification
routing: jump-oriented metadata (tty, mux, mux session, terminal app hints, tmux pane target, zellij tab candidates/match when available)
capabilities: currently hasUI
extensions:
- telemetry: extension presence (@jademind/pi-telemetry, always active when snapshot exists)
- bridge: per-PID bridge activity (@jademind/pi-bridge) inferred from ~/.pi/agent/statusbridge/registry/<pid>.json freshness
messages.lastAssistantText: latest assistant response text when available via Pi API
messages.lastAssistantHtml: HTML-safe rendering of latest assistant text (<div class="pi-last-assistant"><pre>...</pre></div>)
messages.lastAssistantUpdatedAt: timestamp (ms) for latest assistant text capture
lastEvent: most recent triggering Pi lifecycle event
telemetry: snapshot-side metadata (alive, stale, ageMs, source file)

Context pressure model

Derived from context.percent:

normal
approaching_limit (>= PI_TELEMETRY_CLOSE_PERCENT)
near_limit (>= PI_TELEMETRY_NEAR_PERCENT)
at_limit (>= 100)

Additional booleans are provided for easy filtering:

closeToLimit
nearLimit

Example integration

macOS status bar app (open source / free)

pi-statusbar: a free macOS status bar application for Pi built on top of pi-telemetry.
PiTalk: an additional open-source integration example using pi-telemetry.

Poll from a daemon

pi-telemetry-snapshot | jq '.aggregate, .counts, .context'

Get all sessions currently near context limit

pi-telemetry-snapshot | jq '
  .sessions
  | to_entries
  | map(select(.value.context.nearLimit > 0))
'

Check whether any Pi is waiting for input

pi-telemetry-snapshot | jq '.counts.waiting_input > 0'

Development

npm pack --dry-run
node ./bin/pi-telemetry-snapshot.mjs --pretty

Suggested release checklist:

Update version in package.json
Validate tarball with npm pack --dry-run
Verify CLI output in a live Pi session
Tag and publish

Security model

Telemetry is written to the local filesystem under your user account.
Consumers should treat files as untrusted input and validate JSON.
Snapshot CLI performs liveness/staleness filtering; downstream systems should still apply their own policy checks.

OSS best practices

Keep package references scoped (@jademind/pi-telemetry, @jademind/pi-bridge) in all docs/examples.
Preserve backward compatibility in schema fields where possible; document additive vs breaking changes.
Prefer atomic writes and bounded payload size to protect downstream readers.
Keep release notes aligned across npm package, Git tag, and dependent integrations (status bar / mobile clients).

License

MIT — see LICENSE.