@astronova-ai/pi-provider

[!IMPORTANT] This is an independent, unofficial package. It is not endorsed by, affiliated with, or supported by Salesforce. Salesforce is a trademark of Salesforce, Inc. Use requires an entitled Salesforce org and remains subject to your agreements with Salesforce.

A pi extension that registers the Salesforce LLM Gateway as a model provider. Use the Claude / GPT models your Salesforce org is entitled to, from inside pi — no separate model API key.

Install & use

pi -e @astronova-ai/pi-provider

Then, inside pi:

/login salesforce-gateway      # OAuth device flow (opens a URL + shows a code)
/model salesforce-gateway/llmgateway__BedrockAnthropicClaude46Sonnet

Or skip OAuth entirely with environment variables (handy in CI / dev):

SF_ACCESS_TOKEN=00D...  SF_INSTANCE_URL=https://your-org.my.salesforce.com  pi -e @astronova-ai/pi-provider

What it registers

• Provider id: salesforce-gateway
• Models: all 8 gateway models (Claude Sonnet/Opus 4.5–4.7, GPT-5/5.4/5.5), keyed by gateway id. Cost is reported as 0 because inference bills against your org, not a per-token account.
• streamSimple: a custom implementation that runs @astronova-ai/sf-llm-core's unified client and maps its chunks to pi's event protocol (start → text_* → toolcall_* → done/error). Tool calls, token usage, and reasoning effort are surfaced.
• Surface routing (automatic): GPT models stream through the newer Responses API; Claude models through chat/generations (the Responses API is GPT-only on the gateway today). You pick a model in pi; the provider picks the surface. When Salesforce enables Claude on the Responses API, it upgrades with no change. pi's thinking level maps to Responses reasoning effort (xhigh → high).
• OAuth: Salesforce Device Flow — no loopback server. Uses the public PlatformCLI connected app by default; override with SF_OAUTH_CLIENT_ID / SF_LOGIN_URL for a custom connected app or a sandbox.

How the org URL is carried (the interesting bit)

pi persists OAuth credentials as { refresh, access, expires } — but minting a Salesforce gateway JWT also needs the org's instanceUrl. pi's OAuthCredentials has a [key: string]: unknown index signature and round-trips the whole object through ~/.pi/agent/auth.json, so we store instanceUrl (and the chosen featureId) as extra keys. They come back in refreshToken(cred).

streamSimple only receives options.apiKey (the string getApiKey(cred) returns) — not the credential object — so getApiKey packs { accessToken, instanceUrl, featureId } into that string (sfgw1:<base64url>), and streamSimple unpacks it. A bare token from the env path is also accepted. This path is verified end-to-end against a live org (text + tool calls).

Configuration

| Env var | Purpose | |---|---| | SF_ACCESS_TOKEN + SF_INSTANCE_URL | Use a token directly, skipping /login. | | SF_FEATURE_ID | JWT-mint feature id (default AgentforceVibes). | | SF_OAUTH_CLIENT_ID | Custom connected-app client id for OAuth. | | SF_LOGIN_URL | https://login.salesforce.com (prod) or https://test.salesforce.com (sandbox). |

Verified in the real pi CLI

Run against the installed pi CLI (v0.79.9) and a live org, via the env-var path:

$ SF_ACCESS_TOKEN=… SF_INSTANCE_URL=https://your-org.my.salesforce.com SF_FEATURE_ID=AgentforceVibes \
  pi -e @astronova-ai/pi-provider \
     --provider salesforce-gateway \
     --model salesforce-gateway/llmgateway__BedrockAnthropicClaude46Sonnet \
     --print "Reply with exactly: PI VIA SALESFORCE GATEWAY"

PI VIA SALESFORCE GATEWAY

Claude Opus 4.7 works too (the client auto-strips the deprecated temperature param):

$ pi -e @astronova-ai/pi-provider --provider salesforce-gateway \
     --model salesforce-gateway/llmgateway__BedrockAnthropicClaude47Opus \
     --print "List two Salesforce products as a bulleted list. Be brief."

- Sales Cloud
- Service Cloud

Two things to know:

• Loading: pi -e <path-to-this-package> works against both the built dist/index.js and the source src/index.ts (pi's jiti loader aliases the bundled pi-ai for .ts extensions; the built form uses our self-contained fallback runtime). For day-to-day use, pi install it.
• Auth gate: pi checks for a provider key before calling streamSimple, so the provider declares apiKey: "$SF_ACCESS_TOKEN". The env path needs SF_INSTANCE_URL too; /login salesforce-gateway (OAuth device flow) carries the instance URL automatically.

Peer dependencies

@earendil-works/pi-coding-agent and @earendil-works/pi-ai are peer dependencies provided by the pi host. The package falls back to a small bundled event-stream implementation when pi-ai isn't importable (e.g. unit tests / standalone embedding).

License

MIT