docs(pi): add integration docs and example (not intended to merge)

[eersnington]

Adds the Pi page at /integrations/pi, its quickstart snippets, and examples/pi-credentials.

• Quickstart: install, define the actor, add a sandbox, send a prompt, deploy.
• Configuration table and tracing.
• Bring your subscription: credentials backed by a credentials actor.
• examples/pi-credentials: a credentials actor that stores and refreshes each user's logins, and pnpm provider-login to try it.

[claude]

Review: docs(pi): add integration docs and example

The example is small and reads well. A few things to look at before merge.

Scope and description mismatch

• The title and description mention the /integrations/pi page and quickstart snippets. This diff only has examples/pi-credentials, a lockfile change, and one docs edit. If those pages are in another PR in the stack, the description should say so.
• docs/general/content/index.mdx un-hides the Agents card. The comment it removes says "Agents is built but unlaunched (see HIDDEN.md)". This is a launch decision unrelated to Pi. Please confirm it is intended, and if so put it in its own change and update HIDDEN.md.

pnpm-lock.yaml

• The lockfile has about 300 lines of unrelated churn: aws-sdk, smithy, undici and semver bumps and dedupes. It looks regenerated rather than scoped to the new importer. Please limit it to the examples/pi-credentials importer and its new transitive dependencies, or say why the wider bump is needed.

examples/pi-credentials/src/actors.ts

• Concurrent refresh. refresh is async and writes c.state.saved[provider] after several awaits. If two Pi actors for the same user call it at once, both can refresh with the same refresh token. Providers that rotate refresh tokens reject the second use, so the loser can store a stale token. Serialize per provider (for example an in-flight promise map) or note the limitation.
• read on expired tokens. read returns the access token without checking expiry, so it only works if the caller calls refresh first. Please confirm how pi({ credentials }) uses these actions and document it if the caller has to do it.
• Unauthenticated actor. The README says to add authentication. Since this is copy-paste code that stores OAuth tokens, add an onBeforeConnect or createConnState stub showing where the check goes, including that the caller matches the actor key.
• Plaintext state. Credentials are stored in plaintext actor state. Fine for an example, but a one-line comment would help.

scripts/provider-login.ts

• The select prompt falls back to the raw answer when the number is out of range, so a typo silently sends an arbitrary string as an option id.
• The readline interface is never closed and the script relies on process.exit(0). terminal.close() in a finally is cleaner and covers login failures.
• provider is not validated. An empty string gives an obscure error from runtime.login.

package.json

• Check "stableVersion": "0.8.0" and "version": "2.0.21" against the neighbouring examples/*/package.json.
• The scripts run .ts files directly with node, which needs Node 22.6+. Consider an engines field.

Tests

• There is no coverage for the credentials actor, for example that read never returns refresh and that refresh persists the rotated credential. The repo forbids module mocks, so this would need a real registry or driver test.

[the-company-company]

🟠 2 medium · 🔵 1 low

_{Reviewed commit e5040f4.}

[the-company-company]

🟠 2 medium · 🔵 1 low

_{Reviewed commit 89a5bd7.}

[the-company-company]

🟠 Medium · Credential actions expose provider tokens to every caller

read returns the stored API key or OAuth access token, and save also lets an unauthenticated caller replace it. Because this actor has no connection or action authorization, anyone who can reach it and select a user's actor key can steal or overwrite that user's login; the README warning does not enforce the boundary. Make the credential store inaccessible to public actor clients, or add authentication and actor-key authorization to the example before exposing these actions.

[eersnington]

no shit?