@counterposition/skill-pi 0.74.1 → 0.78.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@counterposition/skill-pi",
-  "version": "0.74.1",
+  "version": "0.78.1",
   "description": "Pi coding agent reference skill — extensions, settings, providers, SDK/RPC, packages, and .pi/ config",
   "keywords": [
     "ai-skill",

package/skills/pi/references/extensions.md

@@ -82,7 +82,7 @@ Useful session events:
 
 Useful agent events:
 
-- `input`
+- `input` — carries `event.streamingBehavior` (`"steer" | "followUp" | undefined`) so handlers can distinguish idle prompts, mid-stream steers, and queued follow-ups; return `{ action: "transform" | "handled" | "continue" }`
 - `before_agent_start` — receives `event.systemPromptOptions` (a `BuildSystemPromptOptions`) so handlers can inspect the structured inputs feeding the system prompt
 - `agent_start`
 - `agent_end`
@@ -111,19 +111,23 @@ Tool results may include `terminate: true` to end the current tool batch without
 
 ## Extension Context
 
-`ctx` gives extensions access to:
+`ctx` (`ExtensionContext`) gives extensions access to:
 
 - `ctx.ui` for interactive UI hooks
+- `ctx.mode` — `"tui" | "rpc" | "json" | "print"`; gate terminal-only features on `ctx.mode === "tui"`
 - `ctx.cwd`
-- `ctx.session`
-- `ctx.sessionManager`
-- `ctx.modelRegistry`
-- `ctx.hasUI`
-- `ctx.isIdle()`
-- `ctx.abort()`
+- `ctx.sessionManager` (read-only)
+- `ctx.modelRegistry` / `ctx.model`
+- `ctx.hasUI` — `true` in TUI and RPC modes
+- `ctx.signal` — the active agent abort signal (or `undefined` when idle); pass it to `fetch`/model calls for abort-aware nested work
+- `ctx.isIdle()` / `ctx.hasPendingMessages()`
+- `ctx.abort()` / `ctx.shutdown()`
 - `ctx.getContextUsage()`
+- `ctx.compact(options?)` — trigger compaction without awaiting completion
 - `ctx.getSystemPrompt()`
 
+Command handlers receive `ExtensionCommandContext`, which extends the above with session-control methods that would deadlock from event handlers: `ctx.getSystemPromptOptions()` (inspect the base system-prompt inputs), `ctx.waitForIdle()`, `ctx.newSession()`, `ctx.fork()`, `ctx.switchSession()`, `ctx.navigateTree()`, and `ctx.reload()`.
+
 ## Tool Registration
 
 ```typescript
@@ -149,6 +153,8 @@ pi.registerTool({
 });
 ```
 
+Optional prompt metadata: add `promptSnippet` to give the tool a one-line entry in the system prompt's `Available tools` list, and `promptGuidelines: string[]` to append bullets to the `Guidelines` section while the tool is active. Guidelines are appended flat with no tool-name prefix, so each bullet must name its tool (write `"Use my_tool when..."`, not `"Use this tool when..."`). `pi.getAllTools()` exposes each tool's `promptGuidelines` for attribution.
+
 Important rules:
 
 1. Truncate large output.

package/skills/pi/references/packages.md

@@ -23,7 +23,7 @@ pi update <source>        # update one package
 pi config
 ```
 
-By default, `install` and `remove` write to global settings (`~/.pi/agent/settings.json`). Use `-l` to write to project settings (`.pi/settings.json`) instead.
+By default, `install` and `remove` write to user settings (`~/.pi/agent/settings.json`). Use `-l` to write to project settings (`.pi/settings.json`) instead.
 
 Project installs are shareable with a team. Pi will install missing project packages automatically on startup.
 
@@ -38,7 +38,7 @@ npm:@scope/pkg@1.2.3
 npm:pkg
 ```
 
-- Global installs use `npm install -g`
+- User installs go under `~/.pi/agent/npm/`
 - Project installs go under `.pi/npm/`
 - Version-pinned installs are skipped by `pi update`
 - Use `npmCommand` in settings if you need a wrapper such as `mise` or `asdf`

package/skills/pi/references/providers.md

@@ -7,7 +7,7 @@ Pi supports subscription-based providers via OAuth, API-key providers via env va
 Use `/login` in interactive mode, then select a provider. The `/login` selector is fuzzy-searchable and shows where each entry's auth comes from (`--api-key`, env var, custom provider) without leaking the secret.
 
 - Anthropic Claude Pro / Max — third-party usage draws from extra usage and is billed per token (suppress the warning via `warnings.anthropicExtraUsage`)
-- OpenAI ChatGPT Plus / Pro (Codex)
+- OpenAI ChatGPT Plus / Pro (Codex) — `/login` defaults to browser auth but can use a device-code flow for headless environments
 - GitHub Copilot
 
 Use `/logout` to clear stored OAuth credentials. Pi 0.71.0 removed built-in Google Gemini CLI and Google Antigravity providers.
@@ -17,9 +17,11 @@ Use `/logout` to clear stored OAuth credentials. Pi 0.71.0 removed built-in Goog
 | Provider | Env Var | `auth.json` key |
 |----------|---------|-----------------|
 | Anthropic | `ANTHROPIC_API_KEY` | `anthropic` |
+| Ant Ling | `ANT_LING_API_KEY` | `ant-ling` |
 | Azure OpenAI Responses | `AZURE_OPENAI_API_KEY` | `azure-openai-responses` |
 | OpenAI | `OPENAI_API_KEY` | `openai` |
 | DeepSeek | `DEEPSEEK_API_KEY` | `deepseek` |
+| NVIDIA NIM | `NVIDIA_API_KEY` | `nvidia` |
 | Google Gemini | `GEMINI_API_KEY` | `google` |
 | Mistral | `MISTRAL_API_KEY` | `mistral` |
 | Groq | `GROQ_API_KEY` | `groq` |
@@ -30,6 +32,7 @@ Use `/logout` to clear stored OAuth credentials. Pi 0.71.0 removed built-in Goog
 | OpenRouter | `OPENROUTER_API_KEY` | `openrouter` |
 | Vercel AI Gateway | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway` |
 | ZAI | `ZAI_API_KEY` | `zai` |
+| ZAI Coding Plan (China) | `ZAI_CODING_CN_API_KEY` | `zai-coding-cn` |
 | OpenCode Zen | `OPENCODE_API_KEY` | `opencode` |
 | OpenCode Go | `OPENCODE_API_KEY` | `opencode-go` |
 | Hugging Face | `HF_TOKEN` | `huggingface` |

package/skills/pi/references/sdk.md

@@ -66,10 +66,10 @@ const { session } = await createAgentSession({
   agentDir: "~/.pi/agent",
   authStorage,
   modelRegistry,
-  model: getModel("anthropic", "claude-opus-4-7"),
+  model: getModel("anthropic", "claude-opus-4-8"),
   thinkingLevel: "medium",
   scopedModels: [
-    { model: getModel("anthropic", "claude-opus-4-7"), thinkingLevel: "high" },
+    { model: getModel("anthropic", "claude-opus-4-8"), thinkingLevel: "high" },
   ],
   tools: ["read", "bash", "edit", "write"],
   customTools: [/* defineTool(...) entries */],

package/skills/pi/references/settings.md

@@ -65,11 +65,10 @@ Edit JSON directly or use `/settings` for common interactive options.
     "enabled": true,
     "maxRetries": 3,
     "baseDelayMs": 2000,
-    "maxDelayMs": 60000,
     "provider": {
-      "timeoutMs": 0,
+      "timeoutMs": 3600000,
       "maxRetries": 0,
-      "maxRetryDelayMs": 0
+      "maxRetryDelayMs": 60000
     }
   }
 }
@@ -77,8 +76,9 @@ Edit JSON directly or use `/settings` for common interactive options.
 
 Notes:
 
-- `retry.maxDelayMs = 0` disables the cap on server-requested retry delays.
-- `retry.provider.*` (Pi 0.70.1) controls the underlying provider SDK's request timeout and retry/backoff — useful for slow local LLMs and flaky proxies. Pi forwards these into `streamSimple` request options when set.
+- `retry.maxRetries` (default `3`) and `retry.baseDelayMs` (default `2000`) govern Pi's own agent-level retry with exponential backoff.
+- `retry.provider.*` controls the underlying provider SDK's request timeout and retry/backoff — useful for slow local LLMs and flaky proxies. `retry.provider.timeoutMs` sets the SDK request timeout; `retry.provider.maxRetries` defaults to `0` (keep it there unless you need SDK-level retries, since raising it can let provider retries swallow usage-limit errors before Pi handles them).
+- `retry.provider.maxRetryDelayMs` (default `60000`) caps how long a server-requested retry delay can be before the request fails immediately with an informative error; set to `0` to disable the cap. The old top-level `retry.maxDelayMs` was renamed to this and is auto-migrated.
 - `branchSummary.skipPrompt` skips the confirmation step when navigating with `/tree`.
 
 ## Message Delivery
@@ -87,12 +87,16 @@ Notes:
 {
   "steeringMode": "one-at-a-time",
   "followUpMode": "one-at-a-time",
-  "transport": "sse"
+  "transport": "auto",
+  "httpIdleTimeoutMs": 300000,
+  "websocketConnectTimeoutMs": 15000
 }
 ```
 
 - `steeringMode` and `followUpMode`: `"all"` or `"one-at-a-time"`
-- `transport`: `"sse"`, `"websocket"`, or `"auto"`
+- `transport` (default `"auto"`): `"sse"`, `"websocket"`, `"websocket-cached"`, or `"auto"` — the preferred transport for providers that support several
+- `httpIdleTimeoutMs` (default `300000`) is the HTTP header/body idle timeout, also applied as the default SDK request timeout for providers that support it (e.g. OpenAI Codex WebSocket waits, llama.cpp). Set to `0` to disable.
+- `websocketConnectTimeoutMs` (default `15000`) bounds the WebSocket connect/open handshake. Set to `0` to disable.
 
 ## Terminal, Images, and Shell
 
@@ -114,7 +118,7 @@ Notes:
 }
 ```
 
-- `npmCommand` is argv-style and is used for npm lookup/install operations, including git-package installs.
+- `npmCommand` is argv-style and is used for npm lookup/install operations, including git-package installs. User-scoped npm packages install under `~/.pi/agent/npm/`; project-scoped npm packages install under `.pi/npm/`.
 - `terminal.showTerminalProgress` (default `false` since Pi 0.70.0) toggles OSC 9;4 progress reporting in supporting terminals (iTerm2, WezTerm, Windows Terminal, Kitty).
 - `terminal.imageWidthCells` (Pi 0.68.1) caps inline tool-output image width in terminal cells.
 
@@ -218,12 +222,15 @@ pi [options] [@files...] [messages...]
 -c, --continue                   continue most recent session
 -r, --resume                     browse and select
 --session <path|id>
+--session-id <id>                use an exact project-local session id, creating it if missing
 --fork <path|id>
 --session-dir <dir>
+-n, --name <name>                set the session display name at startup
 --no-session                     ephemeral
 
 # tools and resources
 --tools <list>, -t               name allowlist (read,bash,edit,write,grep,find,ls,...)
+--exclude-tools <list>, -xt      disable specific built-in/extension/custom tools, keep the rest
 --no-tools, -nt                  disable everything
 --no-builtin-tools, -nbt         disable built-ins, keep extension/custom
 -e, --extension <source>         repeatable; npm/git/path
@@ -248,7 +255,7 @@ pi [options] [@files...] [messages...]
 | `PI_PACKAGE_DIR` | Override package storage directory |
 | `PI_SKIP_VERSION_CHECK` | Skip the `pi.dev` latest-version request at startup |
 | `PI_OFFLINE` | Disable all startup network operations (update checks, telemetry) |
-| `PI_TELEMETRY` | Force install telemetry on/off (`1`/`0`); does not gate update checks |
+| `PI_TELEMETRY` | Override install/update telemetry and provider attribution headers (`1`/`0`); does not gate update checks |
 | `PI_CACHE_RETENTION` | Set to `long` for extended prompt-cache retention where supported |
 | `PI_OAUTH_CALLBACK_HOST` | Bind the OAuth callback server to a custom interface |
 | `PI_CODING_AGENT=true` | Set automatically at startup so subprocesses can detect Pi |