Compress‑ShpChat

SYNOPSIS

Drops the oldest exchanges from the running session conversation so it fits within a token budget again, keeping the rest.

SYNTAX

Compress-ShpChat [[-MaxTokens] <Int32>] [[-Model] <String>] [[-Focus] <String>]
 [-WhatIf] [-Confirm] [<CommonParameters>]

DESCRIPTION

Recovers a session that has outgrown the model's context window without discarding it.

Invoke-Shp continues the session conversation by default and writes the conversation back only when a call SUCCEEDS. Once a call is refused for prompt size, the stored conversation therefore stays pinned at its oversized state and every later call is refused identically - measured at 0 successes in 108 retries. Until now the only ways out were Clear-ShpChat and a stateless -History call, and both throw the whole conversation away. Measured against the live service, dropping the single oldest exchange was enough to restore a pinned session, so discarding all of it was never necessary.

This cmdlet is deliberately explicit rather than something Invoke-Shp does on its own. A tool result is scaffolding the model produced for itself and the context guard elides it automatically; a user turn is something the user said, and a model answering from a silently truncated history can confidently contradict what was established earlier. The module already draws that line for sampling, where a quietly dropped setting would return a plausible answer while destroying a guarantee the caller depends on.

What is preserved, in order of priority: the newest exchange, which is the one still in play; and the first exchange, which usually carries the task definition and is the worst thing to lose. Exchanges are dropped oldest-first from between those two anchors, and always as whole user/assistant pairs - an answer whose question was dropped describes something the model can no longer see. The first exchange is given up only when nothing else remains to drop, and the report says so. If not even the newest exchange fits, nothing more is removed and the report says the conversation still does not fit, because silently emptying it would just be Clear-ShpChat under another name.

EXAMPLES

EXAMPLE 1

Compress-ShpChat

Trims the running conversation to fit the current model's window, keeping the task definition and the most recent exchanges.

EXAMPLE 2

Compress-ShpChat -WhatIf

Reports which exchanges would be dropped without changing anything.

EXAMPLE 3

Compress-ShpChat -MaxTokens 40000

Trims the conversation to roughly 40000 estimated tokens.

EXAMPLE 4

Compress-ShpChat -Focus 'the failing deployment pipeline'

Trims the conversation, giving up exchanges unrelated to the deployment pipeline before the ones that mention it.

PARAMETERS

-Focus

One short caller instruction naming what this compression must try to keep - for example 'the widget inventory numbers'. It is the CALLER's statement of intent, never anything discovered in the conversation, and it is treated strictly as data: the text is split on Unicode letter/digit boundaries and the resulting tokens are compared case-insensitively for overlap. It is never used as a regular expression, a path, or executable text, and it is never added to the conversation - nothing the model sees changes because a Focus was given.

A Focus only reorders what is given up. The anchors are unchanged: the newest exchange is still kept, the first exchange is still surrendered last, and exchanges are still dropped whole. Between the anchors, an exchange sharing no token with the Focus is dropped before one that does; ties keep the oldest-first order, so an unbound Focus behaves exactly as before.

The Focus is redacted before it is reported or traced, and the redacted form is what the tokens are taken from, so a secret pasted into a Focus is neither echoed back nor used as a search key. At most 1024 characters; whitespace-only is refused. Redaction and validation both run before anything is removed, so a refusal leaves the conversation exactly as it was.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 3
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-MaxTokens

Estimated-token budget the stored conversation must fit within. Omit it to derive one from the model: the resolved context budget (see Invoke-Shp -MaxContextWindowTokens) reduced to leave headroom for the next prompt and its reply, because trimming to the full budget would leave no room to ask anything.

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: 1
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False

-Model

Model whose context window the default budget is derived from. Defaults to the model that produced the running conversation, then to the session default from Select-ShpModel. Ignored when -MaxTokens is given.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Confirm

Prompts you for confirmation before running the cmdlet.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: cf

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: wi

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

OUTPUTS

System.Management.Automation.PSCustomObject

A ShellPilot.ChatCompressionReport with MaxTokens and where it came from,

the estimate before and after, how many exchanges and turns were removed,

whether the first exchange had to be given up, whether the conversation

now fits, and the redacted Focus with how many exchanges matched it and

how many of those survived.

NOTES

RELATED LINKS

Get-ShpChat

Clear-ShpChat

Invoke-Shp