Use the Pi TypeScript SDK for in-process integrations with Pi's coding agent. Ground every API name, import, option, and event in documentation or types that match the installed Pi version. Do not infer SDK behavior from the CLI alone.
Workflow
- Read reading.md to identify the installed package, SDK documentation, version, and any source-checkout mismatch.
- Read patterns.md for the part of the SDK the task uses: sessions, runtime replacement, events, tools, resources, models, or run modes.
- If the application uses Effect v4, read effect-integration.md and the applicable branches of the repository's Effect skill.
- If the application should use a ChatGPT Plus/Pro Codex subscription, read openai-codex-subscription.md.
- Prefer the smallest surface that meets the requirement:
- SDK for in-process TypeScript control;
- RPC for process isolation or language-independent control;
- CLI/print/JSON mode for shell-level automation.
- Inspect the project’s package manager, TypeScript configuration, and existing integration conventions before adding imports or dependencies.
- Validate with the project’s narrowest meaningful typecheck, test, or smoke command. Report the Pi version, package/docs source, files inspected, and any mismatch or unverified assumption.
Safety boundaries
- A session can expose
bash,edit, andwrite; use an explicit read-only tool allowlist (read,grep,find,ls) for documentation or inspection tasks. - Do not print, copy, commit, or hard-code
auth.json, API keys, OAuth tokens, provider headers,models.jsonsecrets, sessions, or machine-specific paths. ModelRuntimemay read Pi credentials and model configuration. Prefer an in-memory credential store or explicit non-persisting runtime overrides when a test needs credentials, and never expose their values.- Do not silently fall back from a requested local model or provider to a cloud provider. Verify the selected model and endpoint separately.
- Do not install packages, alter Pi settings, or run an agent with write tools merely to answer a documentation question.
API routing
- Basic prompt, streaming text, abort, or cleanup:
AgentSession. - New session, switch, fork, clone, or JSONL import:
AgentSessionRuntime. - Prompt queueing during a stream:
steer()versusfollowUp(); read the version-matched prompt behavior before choosing. - Custom tools:
defineTool()andcustomTools, or an extension when the behavior needs lifecycle hooks, commands, or UI. - Skills, extensions, prompt templates, themes, and context files: use a
ResourceLoader; checkcwdandagentDirdiscovery semantics. - Model selection and authentication: use
ModelRuntime; distinguish model resolution from credential availability. - Effect integration: wrap the SDK at a service/layer boundary; do not spread
raw
AgentSessionor provider state through unrelated application code.
Completion checklist
- Installed
piversion and package scope were checked. - The matching
sdk.md, types, source, or official docs were read. - SDK, RPC, and CLI boundaries are explicit.
- Tools and credential behavior are least-privilege and non-leaking.
- The integration was typechecked/tested or the validation limitation is stated plainly.