ShellPilot

Author(s)

• raandree

Tags

GitHubCopilot Copilot AI LLM Chat Agent

Functions

Clear-ShpChat Clear-ShpContext Clear-ShpRedactionPolicy Clear-ShpToolPolicy Clear-ShpUsage Compress-ShpChat ConvertTo-ShpAnnotation ConvertTo-ShpTokenCount Get-ShpChat Get-ShpContext Get-ShpCosineSimilarity Get-ShpCostEstimate Get-ShpDefault Get-ShpMcpServer Get-ShpModel Get-ShpModelName Get-ShpRedactionPolicy Get-ShpTool Get-ShpToolPolicy Get-ShpUsage Initialize-Shp Invoke-Shp Invoke-ShpBatch Register-ShpMcpServer Register-ShpTool Request-ShpEmbedding Resolve-ShpError Select-ShpModel Set-ShpContext Set-ShpRedactionPolicy Set-ShpToolPolicy Start-ShpChat Test-ShpCiReadiness Unregister-ShpMcpServer Unregister-ShpTool

PSEditions

Core

Dependencies

This module has no dependencies.

Release Notes

## [0.4.0-preview0010] - 2026-08-26

### Added

- **`ConvertTo-ShpAnnotation` surfaces structured findings in CI.** Pipe a
 `ShellPilot.Result` from `Invoke-Shp -JsonSchema`, or any plain finding
 object, into the cmdlet to produce GitHub Actions annotations, Azure DevOps
 `task.logissue` commands, or readable text. `Level`, `Path`, `Line`,
 `Column`, `Title`, and `Message` are matched case-insensitively and can be
 redirected with `-PropertyMap`; an unknown or missing level is always a
 warning. Vendor-specific escaping keeps newlines and delimiters from
 corrupting a workflow command. Output stays on the success stream unless
 `-Emit` writes it to the host, and `-Summary` appends a Markdown table to
 `$env:GITHUB_STEP_SUMMARY` when available.
 See [specs/028-ci-annotations.md](specs/028-ci-annotations.md).

- **`Invoke-Shp -EventStream <path>` writes a headless JSONL event stream.** A
 CI log collector reads lines, not prose: everything the module said about a
 running turn was aimed at a person, so a nineteen-iteration turn that was
 refused twice by the tool policy, retried once on an expired session token
 and then stopped on `-MaxBudgetUSD` left one object saying
 `BudgetExceeded = $true` and nothing about the shape of the failure. The
 stream appends one JSON object per line - `turn.start`, `model.request`,
 `usage`, `reasoning` (one per streamed chunk under `-ShowThinking`),
 `tool.call`, `tool.result`, `todo`, `retry`, `error`, `final` - each carrying
 `schemaVersion`, a monotonic `sequence`, an ISO 8601 UTC `timestamp`, a
 `type` and a flat `data` object. Pass `-` to write the records to the
 Information stream instead of a file. Every line is appended whole, so a run
 killed mid-turn still leaves a file that parses up to its last complete line;
 a later call appending to that valid stream continues the sequence. Every
 string payload goes through the same redaction seam the request body does, so
 a secret a tool printed does not reach the stream verbatim; a `run_command`
 tool-call record names the tool and the policy decision but never the command
 line. The complete streamed reasoning trace is redacted before it is divided
 back into Event records, so an SSE boundary cannot split a secret around the
 redaction seam; partial reasoning is retained before a `retry` or `error`.
 Transient HTTP and network-outage retries from the shared request wrapper are
 recorded with attempt, delay and status data, and an invented `ask_user` call
 in a non-interactive turn records its denied Tool call and terminal error
 before the call stops. `-DisableProgressEvents` no longer switches this off -
 the two sinks are gated independently.
 See [specs/027-headless-event-stream.md](specs/027-headless-event-stream.md).

- **`Invoke-Shp -AsJob` and `Invoke-ShpBatch -AsJob` run a call in the
 background.** Both return a thread job whose `Receive-Job` resolves to the
 same `ShellPilot.Result` / `ShellPilot.BatchResult` objects the synchronous
 call returns - the same process, so nothing is serialised into a
 `Deserialized.*` copy. The job runspace inherits no module state, so the
 session context, session defaults, cached model limits, tool policy,
 redaction policy and registered tools are replayed into it and the module is
 imported by path. `Invoke-Shp -AsJob` is seeded from a snapshot of the
 session conversation and stays stateless from there, because a job that
 finishes at an arbitrary time must not race the caller's next call. The CI
 entitlement gate is still evaluated at the call site, so a refused backend
 fails where you typed it rather than in the background of a green build. An
 event stream is honoured: `-AsJob` does not silently turn it off.
 See [specs/027-headless-event-stream.md](specs/027-headless-event-stream.md).

- **`Invoke-Shp` now redacts secrets before they leave the runner.** A CI job
 feeds the model diffs, build logs and attachments produced by untrusted
 pull-request content, and nothing scrubbed them before now - a leaked token
 in a log became a token sent to a third party. Immediately before each
 round-trip, the prompt, every inlined `-Attachment`, and every tool result
 (`run_command`, `read_file`, `fetch_url`, an MCP tool, a user-defined tool)
 is scanned for six built-in shapes - GitHub tokens, AWS access key ids, PEM
 private-key blocks, JWTs, basic-auth URL credentials, and connection-string
 password fields - and a match is replaced with a stable, named placeholder
 such as `[redacted:github-token]`, never simply deleted. The result reports
 `Redactions`: pattern name and count only, never the matched value.
 `Set-ShpRedactionPolicy` / `Get-ShpRedactionPolicy` / `Clear-ShpRedactionPolicy`
 add custom patterns on top of the built-ins, in the same `Name(Pattern)`
 shape `Set-ShpToolPolicy` already uses, and the custom policy travels to
 every `Invoke-ShpBatch` worker the same way the tool policy does. Redaction
 is on by default; pass `-DisableRedaction` to send a call verbatim. Only the
 model's own reply is exempt - it was generated from input already redacted
 before it was sent, so it cannot reflect a secret it was never shown, and a
 `-JsonSchema` reply still parses onto `ContentObject` exactly as it would
 with redaction off.
 See [specs/026-egress-redaction.md](specs/026-egress-redaction.md).

- **An unattended run is now a supported, deliberate profile rather than an
 accident.** `Invoke-Shp`, `Invoke-ShpBatch` and `Initialize-Shp` take
 `-NonInteractive`, on automatically when `$env:CI` is truthy and overridable
 with `-NonInteractive:$false`. It withdraws `ask_user`, refuses `-Confirm`
 instead of silently answering it yes, and refuses the device-code flow before
 the browser launch and the clipboard write - because a prompt on a runner does
 not fail, it burns the job's whole timeout and then fails for the wrong
 reason. A model that calls `ask_user` anyway ends the turn with
 `ShpNonInteractivePrompt` rather than continuing on an answer nobody gave.
 See [specs/025-ci-profile.md](specs/025-ci-profile.md).

- **In CI, the default Copilot backend is refused unless you opt in.** That
 backend reaches the Copilot endpoints with the public VS Code client id, on
 the token owner's personal entitlement - fine for a shell, a decision for a
 pipeline. Configure an OpenAI-compatible endpoint instead, or set
 `SHELLPILOT_ALLOW_COPILOT_BACKEND_IN_CI`. The error carries the id
 `ShpCopilotBackendInCi` and names both remedies, and it is raised **before**
 the token exchange so nothing is spent proving the point.
 A warning was the obvious alternative and is the wrong shape: nobody reads a
 warning in a green build, which is the whole finding behind `-FailOn`.

- **`$env:SHELLPILOT_API_BASE` and `$env:SHELLPILOT_API_KEY`** are read as
 backend defaults, below an explicit `-ApiBase` and the session context and
 above the built-in Copilot endpoint - so a pipeline points ShellPilot at its
 own endpoint with the variables it already injects.

- **`Test-ShpCiReadiness`** reports the whole resolved profile - token source,
 backend, interactive capability, `Ready`, and a list of named issues - without
 sending a chat request or exchanging a token. The three things an unattended
 run needs are decided by three different precedence chains with silent
 fallbacks, so a misconfigured job otherwise fails minutes later at the first
 `Invoke-Shp` with whichever chain gave out first. No secret is returned: the
 credential and the API key are reported by source only, and the endpoint has
 any URL credentials redacted.

### Changed

- **An alternative backend (`-ApiBase`) no longer carries the Copilot session
 token.** It previously fell back to that token whenever no `ApiKey` was
 configured. That was reachable before only through `Set-ShpContext`; reading
 `ApiBase` from the environment would have let anything able to set a variable
 on a runner redirect a live Copilot credential to a host of its choosing.
 With a key the request carries the key; without one it carries no
 `Authorization` header at all, which is what a local server expects anyway.
 A URL's credentials are also redacted from the result's `Endpoint` member.

- **A pipeline step can now fail when the call did not deliver.** A budget
 overrun was a `Write-Warning` plus a `BudgetExceeded` property, so an
 unattended run exited `0` on a truncated or abandoned answer and wrote the
 half-finished artifact anyway. `Invoke-Shp -FailOn` turns five named outcomes
 into terminating errors: `BudgetExceeded`, `Truncated`, `ToolIterationLimit`,
 `NoContent` and `SchemaMismatch`.
 Each carries a distinct, documented `FullyQualifiedErrorId`
 (`ShpBudgetExceeded,Invoke-Shp` and so on) so a wrapper branches on the
 condition instead of matching an English message - which is what
 `MaxToolIterations` forced, having used its own message text as the error id.
 **Omitting `-FailOn` changes nothing**, and the turn's side effects are
 unchanged either way: the call is evaluated last, after the result is built,
 the usage row written and the session chat updated, so `-FailOn` decides only
 whether the call ends with a result or with an error. The whole
 `ShellPilot.Result` rides on `ErrorRecord.TargetObject`, so a `catch` block
 still knows what the abandoned turn cost.
 ShellPilot never sets `$LASTEXITCODE` and never calls `exit` - a module that
 terminates its host cannot be composed - so the exit code stays the caller's
 job; the comment-based help carries the `try`/`catch` plus `exit 1` wrapper.
 See [specs/024-pipeline-failure-semantics.md](specs/024-pipeline-failure-semantics.md).

- **`Invoke-ShpBatch -FailOn` and `-FailBatchOnAnyItem`.** The same five
 conditions apply per item, and a tripped one never aborts the batch: the item
 reports `Success = $false` with the branchable `ErrorRecord` intact while every
 other item runs to comp