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.0-preview0005] - 2026-06-12

### 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).

### Fixed

- 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
 correctly; some in-editor Markdown previews may not. The glyph and the Gallery
 icon are also transparent.
- Module icon for the PowerShell Gallery: the manifest now sets `IconUri` to
 the ShellPilot app icon (`assets/shellpilot-icon.png`, a navy rounded square
 on a transparent surround), so the module displays its logo on the Gallery
 once published.
- Todo-list tool and structured progress events. By default `Invoke-Shp` now
 offers the model a native `manage_todo_list` tool so it can maintain a short
 ordered checklist of sub-tasks for a multi-step request (exactly one item
 in-progress at a time, normalised by the new private `ConvertTo-ShpTodoList`);
 the final list is returned on the result's new `TodoList` member. Opt out with
 `-DisableTodoList`, which suppresses both the tool and its built-in planning
 guidance. `Invoke-Shp` also emits structured `ShpProgress` Information-stream
 records for every tool call (`Kind = 'ToolCall'`) and every todo-list update
 (`Kind = 'TodoList'`), so a host can render live tool activity without parsing
 the `-ShowThinking` host trace; opt out with `-DisableProgressEvents`. The
 records are silent on the console under the default `InformationPreference`.
- Table formatting: a `ShellPilot.Format.ps1xml` format file gives the
 structured records a readable default view, so `Get-ShpModel`,
 `Get-ShpUsage` (records and `-Summary`), `Get-ShpTool`, `Get-ShpDefault`,
 `Get-ShpContext` and `Get-ShpCostEstimate` print as clean tables without an
 explicit `Format-Table`. `Get-ShpModel` now hides the bulky `Raw` member by
 default and shows token limits with thousands separators; the full data
 remains on every object via `Select-Object` / `Format-List *`.
- User-defined tools: `Register-ShpTool`, `Get-ShpTool` and
 `Unregister-ShpTool` expose any PowerShell command to the model as a callable
 tool (schema derived from the command's parameter metadata). Invoke-Shp offers
 registered tools alongside its built-in ones and dispatches a tool call by
 invoking the backing command; opt out per call with `-DisableUserTools`.
- Structured output: `Invoke-Shp -ResponseFormat json_object` or `-JsonSchema`
 requests a JSON reply, parsed onto the result's new `ContentObject` member
 (a surrounding Markdown code fence is stripped first). Live-verified.
- Vision input: `Invoke-Shp -Image` sends one or more image files (embedded as
 base64 data URIs) or URLs to vision-capable models on the chat shape.
- `Set-ShpContext`, `Get-ShpContext` and `Clear-ShpContext` manage a session
 context of connection options (HTTP timeout, retry count and delay, and an
 opt-in alternative `ApiBase` / `ApiKey` backend) applied when a call does not
 override them.
- HTTP retry and timeout: API calls now retry transient 429/5xx failures with
 exponential backoff; tune with `Invoke-Shp -TimeoutSec` / `-MaxRetryCount` or
 the session context.
- `Request-ShpEmbedding` generates embedding vectors and `Get-ShpCosineSimilarity`
 ranks them, enabling semantic search from the shell (requires a backend
 embeddings endpoint).
- `ConvertTo-ShpTokenCount` estimates a prompt's token count and
 `Get-ShpCostEstimate` estimates its input cost before sending.
- Pipeline-friendly history: `Invoke-Shp -History` accepts pipeline input by
 property name, so a prior result pipes straight into the next call.
- Server-side conversation state: `Invoke-Shp -UseServerSideState` (opt-in, off
 by default) attempts to store each `/responses` turn and continue by id. The
 Copilot backend is stateless and rejects this, so the call automatically and
 transparently falls back to ordinary client-side history with a warning.
- Alternative model backends: an opt-in `ApiBase` / `ApiKey` override
 (`Set-ShpContext` or `Invoke-Shp -ApiBase`) targets an OpenAI-compatible
 endpoint; never a default.
- `Start-ShpChat` opens an interactive console chat session on top of streaming
 and the running ses