pi-zai is a Z.AI-only Pi extension. This page describes what data leaves your machine, what stays local, and how to control it.

Remote telemetry is off by default. Enable it only through settings plus /zai-telemetry enable. See Architecture — remote telemetry.

Inspect your setup at any time:

/zai-privacy preview
/zai-data status
/zai-telemetry status

• API keys resolve through Pi's ModelRegistry, auth.json, models.json, runtime --api-key, and environment variables such as ZAI_API_KEY and ZAI_CODING_CN_API_KEY.
• The extension never prints key values in commands, logs, or diagnostics.
• /zai and /zai-doctor show credential source names only, such as ZAI_API_KEY or auth.json.

1. Runtime --api-key
2. auth.json for the active provider
3. Provider apiKey from models.json
4. Environment variable

pi-zai does not add separate credential precedence or shell helpers.

When storing keys outside Pi:

chmod 700 ~/.config/zai
chmod 600 ~/.config/zai/credentials.env

Never commit credential files. Rotate keys exposed in chat, logs, screenshots, or shell history.

GitHub secret scanning flags OAuth client IDs and secrets even when they originate from upstream tools (for example pi-mono Gemini CLI / Antigravity embedded credentials). pi-zai must not copy those into docs or source.

Before pushing:

bash scripts/check-secrets.sh

CI runs Gitleaks on the working tree plus the same pattern guard. Historical alerts on orphaned commits can be resolved as false positives once main is clean — they are not org-owned secrets.

Default: zai.metrics.mode: "local". Z.AI attempts can be recorded locally as privacy-reduced rows.

~/.pi/agent/state/pi-zai/metrics.sqlite3
~/.pi/agent/state/pi-zai/local.secret

• local.secret — random 256-bit key for HMAC project identifiers. Never sent remotely.
• projectId — HMAC(localSecret, canonicalCwd). It is not a reversible path hash.
• sessionHash — hash of the Pi session id. Local only.

• Prompt, source-code, or reasoning text
• Tool arguments or tool-result text
• API keys
• Filesystem paths, hostnames, or repository names
• Raw provider error response bodies
• Install identifiers or reversible project paths

Normal inference data still goes to Z.AI through Pi. “Never stored” describes pi-zai's metrics systems, not the provider request required to run the model.

Retention is controlled by retentionDays, rollupRetentionDays, and maxDatabaseBytes. Old detail rows roll up to daily summaries before deletion.

• System prompts are canonicalized before hashing.
• Raw prompt text is never written to SQLite, exports, telemetry, or command output.
• /zai and /zai-cache show short fingerprints only.
• promptStability.mode: observe measures structure without changing the request.
• promptStability.mode: safe can move recognized volatile lines below an existing --- dynamic context --- marker.

See Cache optimization.

Preserved reasoning is part of the normal Z.AI inference request, not pi-zai telemetry. Current Pi releases send clear_thinking=false when Z.AI thinking is enabled and replay compatible historical reasoning through Pi's provider implementation.

The zai.preserveThinking setting is an optional explicit override:

Preserved reasoning can contain sensitive intermediate analysis and therefore leaves your machine as part of normal Z.AI chat traffic. Forcing it off reduces that replay, but can also reduce reasoning continuity and cache reuse in coding/tool workflows. /zai shows the effective policy.

Compaction is a separate boundary: pi-zai asks Pi's compaction process to preserve visible decisions and tool outcomes without replaying hidden reasoning in the compacted summary.

/zai-doctor can make explicit diagnostic requests:

• GET ${baseUrl}/models for reachability
• three short chat completions for connection-stability probing

The probes use configured authentication. Response status and controlled summaries are shown; secrets and response bodies are not logged.

/zai-usage calls Z.AI monitor APIs for Coding Plan quota when credentials exist.

Default: zai.telemetry.mode: "off". Uploads require both:

1. set "telemetry": { "mode": "aggregate" } and reload;
2. run /zai-telemetry enable and confirm consent.

Completed UTC days can upload on session start or /zai-telemetry sync.

Consent file:

~/.pi/agent/state/pi-zai/telemetry.consent.json

Disable with /zai-telemetry disable; the configured mode remains unchanged.

• Prompts, source code, reasoning, tool arguments, or tool results
• Paths, install identifiers, or API keys
• Project/session/query identifiers or fingerprints
• Raw provider error bodies
• IP address as an application payload field

/zai-privacy preview renders the local aggregate shape. Its status remains preview-only-not-sent until both mode and consent are active, then becomes aggregate-ready.

Ingest endpoint: POST https://api.chefgroep.online/pi-zai/telemetry/v1/aggregate. Override zai.telemetry.ingestUrl for staging or self-hosting.

/zai-benchmark stores run manifests and completed reports in the same local SQLite database. Reports contain aggregated usage, transport, and cache statistics for the benchmark window—not prompt or reasoning content.

The package includes tests asserting that:

• remote telemetry fetch is isolated to telemetry/uploader.ts;
• privacy preview does not call the network;
• telemetry requires aggregate mode plus explicit consent;
• payload normalization performs no thinking mutation when no override is configured.

• Local metrics may store toolset fingerprints, counts, and transition classifications.
• Raw tool names, schemas, arguments, and results are not written to metrics or telemetry.
• Session-affinity identifiers may be sent as X-Session-Id only when sessionAffinity=experimental; they are never shown in /zai-doctor output and are never uploaded.
• /zai-capabilities probe stores only boolean/result metadata and HTTP status codes.