ShellPilot

Author(s)

• raandree

Tags

GitHubCopilot Copilot AI LLM Chat Agent

Functions

Clear-ShpChat Clear-ShpContext Clear-ShpUsage ConvertTo-ShpTokenCount Get-ShpChat Get-ShpContext Get-ShpCosineSimilarity Get-ShpCostEstimate Get-ShpDefault Get-ShpModel Get-ShpModelName Get-ShpTool Get-ShpUsage Initialize-Shp Invoke-Shp Register-ShpTool Request-ShpEmbedding Select-ShpModel Set-ShpContext Start-ShpChat Unregister-ShpTool

PSEditions

Core

Dependencies

This module has no dependencies.

Release Notes

## [0.2.1-preview0001] - 2026-07-08

### Added

- Wiki documentation is now generated during the build so the deploy
 `Publish_GitHub_Wiki_Content` step has content to publish. A new `docs` build
 workflow runs `Generate_Wiki_Content` (per-command markdown via PlatyPS +
 external help), `Generate_Wiki_Sidebar`, `Clean_Markdown_Metadata` and
 `Package_Wiki_Content`; `docs` is included in `pack` so the build artifact
 carries `output/WikiContent`. `platyPS` was added to `RequiredModules.psd1`
 (the command-markdown task skips with a warning without it). Note: publishing
 to the wiki also requires the repository wiki to be initialized once (create
 the first page in the GitHub UI).

### Changed

- The default on-disk OAuth token file was renamed from `.copilot-demo-token`
 to `.shellpilot-token` (still a hidden dot-file in the user's home directory).
 The old name dated from ShellPilot's proof-of-concept origin; the new name is
 branded to the module. `-TokenPath` still overrides the location. Because the
 default path changed, existing users must re-run `Initialize-Shp` once to
 write the token under the new name (or pass `-TokenPath` to point at the old
 file); the previous `.copilot-demo-token` file is not migrated automatically
 and can be deleted.
- Cut the per-Turn network overhead so ShellPilot feels closer to the VS Code
 Copilot extension, with no change to the public API, result objects,
 streaming, tool loop, structured output, images, the responses API, retry, or
 network-outage tolerance - the only observable difference is lower latency.
 - The Copilot session token is now cached module-wide and reused until it
   nears expiry, instead of exchanging a fresh one on every Turn.
   `Get-ShpSessionToken` keys a cache (a hash of the OAuth token plus the
   Editor-Version) on the exchange response and returns it while more than a
   60-second safety margin remains before its `expires_at`; a new `-Force`
   switch bypasses the cache, and `Initialize-Shp` clears it on re-auth. A
   second Turn within the token's validity makes no
   `copilot_internal/v2/token` request.
 - All requests now share one pooled `HttpClient` backed by a
   `SocketsHttpHandler` (2-minute `PooledConnectionLifetime`, HTTP/2 preferred),
   built lazily by the new private `Get-ShpHttpClient`. Because a Turn loops one
   API round-trip per tool iteration, reusing one warm connection avoids a fresh
   TCP + TLS handshake per iteration. `Invoke-ShpStreamRequest` now uses the
   shared client (and no longer disposes it), and the non-streaming
   `Invoke-CopilotTurn` path posts through it via the new private
   `Invoke-ShpHttpRequest` (`SendAsync` + `ReadAsStringAsync`), while keeping the
   `Invoke-ShpWithRetry` 429/5xx and network-outage classification intact.

### Fixed

- The deploy `publish` workflow aborted whenever a release did not change the
 generated wiki markdown (for example a fix that only touches a private code
 path). DscResource.DocGenerator's `Publish_GitHub_Wiki_Content` runs
 `git commit` unconditionally and treats the resulting "nothing to commit,
 working tree clean" (git exit code 1) as fatal, which stopped the pipeline
 before `publish_module_to_gallery` — so the module never reached the
 PowerShell Gallery even though the GitHub release was created (this is why
 `0.2.0-preview0006` appeared under GitHub Releases but not on the Gallery).
 Added `source/WikiSource/Home.md` with a `#.#.#` version placeholder. The
 standard `Generate_Wiki_Content` task (via `Copy_Source_Wiki_Folder` and
 `Set-WikiModuleVersion`) substitutes the built module version into the page,
 so the published wiki content changes on every release and the stock
 `Publish_GitHub_Wiki_Content` task always has something to commit. This is the
 wiki landing-page convention DscResource.DocGenerator expects — every
 dsccommunity module ships one and ShellPilot was simply missing it — so the
 fix needs no custom build task and the `publish` workflow keeps using only the
 standard Sampler tasks.
- `Initialize-Shp` failed on Linux/macOS with `Get-Item: Could not find item
 <path>` even though the token file existed and `Test-Path` reported it as
 present. The default token path is a dot-file (`~/.copilot-demo-token`), which
 .NET flags as hidden on Unix, and `Get-Item -LiteralPath` returns nothing for
 a hidden item unless `-Force` is passed. Added `-Force` to the `Get-Item`
 calls in `Initialize-Shp`, and to the `read_file` and `write_file` tools,
 which shared the same latent defect for hidden dot-files. Windows was
 unaffected because a leading dot is not "hidden" there.
- The deploy `Publish_GitHub_Wiki_Content` step failed with "Cannot bind
 argument to parameter 'GitUserEmail' because it is an empty string". The git
 identity was configured under a `GitConfig:` section with `UserName` /
 `UserEmail` keys, but the Sampler.GitHubTasks and DscResource.DocGenerator
 tasks read `$BuildInfo.GitHubConfig.GitHubConfigUserName` /
 `GitHubConfigUserEmail` (and `GitHubFilesToAdd`). Renamed the section to
 `GitHubConfig` with the exact key names the tasks expect, so the wiki publish
 and the changelog-PR step can set the git author identity.

### Added

- The GitHub Actions CI now surfaces the GitVersion build version (the way the
 Azure DevOps pipeline renamed each run). The `build` job exposes the version
 as an output; the test and deploy jobs show it in their display names (e.g.
 `Test 0.6.0-preview0003 (ubuntu-latest)`), the build job writes it to the run
 summary, and tag-triggered runs use `Release <tag>` as the run title.
 (GitHub Actions cannot rename a run mid-run like Azure's
 `##vso[build.updatebuildnumber]`, so the version is shown in job names instead
 of the run title for branch builds.)
- `DscResource.DocGenerator` is now a build dependency
 (`RequiredModules.psd1`) and its tasks are imported via `ModuleBuildTasks`
 (`Task.*`). This provides `Publish_GitHub_Wiki_Content` (plus the
 `Generate_*`/`Package_Wiki_Content` and `*_For_Public_Commands` tasks), which
 the `publish` workflow uses to publish documentation to the repository's
 GitHub wiki.

### Fixed

- `./build.ps1 -Tasks publish` aborted immediately with "Missing task
 'Publish_GitHub_Wiki_Content'" because that task's module
 (`DscResource.DocGenerator`) was not a dependency and its tasks were never
 imported. The module is now declared and wired into `ModuleBuildTasks`, so the
 workflow resolves and the task is available.
- Module import crashed on Linux and macOS. The default token path was built
 with `Join-Path $env:USERPROFILE '.copilot-demo-token'`, but `$env:USERPROFILE`
 is a Windows-only variable and is `$null` elsewhere, so `Join-Path` threw
 "Cannot bind argument to parameter 'Path' because it is null" at load time and
 every command (and the CI test run) failed on non-Windows. The path now uses
 `[System.Environment]::GetFolderPath('UserProfile')`, which resolves to
 `%USERPROFILE%` on Windows and `$HOME` on Linux/macOS.
- `Invoke-Shp -ShowThinking` showed no reasoning trace for models such as
 `claude-opus-4.8`. The switch forced streaming off and routed to the
 `/responses` endpoint, which those models reject - and their non-streaming
 `/chat/completions` reply carries no reasoning. The reasoning trace is in fact
 delivered as `reasoning_text` deltas on the **streaming** `/chat/completions`
 response (the same trace VS Code shows). `-ShowThinking` now keeps streaming
 on and echoes that trace live in dim italic under a `thinking:` label, so it
 is clearly distinct from the answer; it falls back to the `/responses`
 reasoning summary only when `-DisableStreaming` is also passed. When a model
 exposes no reasoning at all, a one-line note now says so instead of leaving
 the thinking output mysteriously empty.
- `Invoke-Shp`'s result printed its answer twice in the default output: the
 answer lives on `Content`, but the object had no format view, so PowerShell
 also dumped the `History` member, which repeats the answer as the assistant
 turn. The result is now tagged `ShellPilot.Result` with a default list view
 that shows the answer once plus the key metadata (model, finish reason, token
 usage, cost, duration); `History`, `Raw` and `Headers` are hidden from the
 default display but remain on the object via `Select-Object` / `Format-List *`.

### Changed

- Replaced the Azure Pipelines CI definition with a GitHub Actions workflow
 (`.github/workflows/ci.yml`). It keeps the same three stages: build and
 package the module (versioned with GitVersion), test on Linux, Windows and
 macOS (PowerShell 7), and deploy - publish the release to GitHub and the
 PowerShell Gallery and raise the changelog pull request - on pushes to `main`
 or `v*` tags from the upstream repository. The deploy stage needs the
 repository secrets `GitHubToken` and `GalleryApiToken`.
- Documentation: filled in the `about_ShellPilot` help topic (previously the
 Plaster placeholder), added a `-ShowThinking` reasoning-trace example to the
 README, and brought the specs (feature map, roadmap statuses, open-decision
 delivery) in line with the shipped status.

### Added

- Brand identity in the docs. The main `README.md` opens with the full
 ShellPilot logo floated to the left, with the intro paragraph filling the
 space to its right (a borderless side-by-side layout - an HTML table can't be
 made borderless on github.com because GitHub draws table-cell borders in CSS
 and strips the style that would remove them); the specs `README.md` keeps the
 glyph floated in its top-right corner. The
 wordmark ships as two transparent variants that switch by theme via a
 `prefers-color-scheme` `<picture>`: a "Shell"-in-white logo on dark backgrounds
 (`assets/shellpilot-logo-on-dark.png`) and a "Shell"-in-black logo on light
 backgrounds (`assets/shellpilot-logo-on-light.png`). GitHub resolves the theme
 corr