Get‑ShpContextReport

SYNOPSIS

Accounts where a request's estimated Context tokens would go, source by source, without sending anything.

SYNTAX

Get-ShpContextReport [[-Prompt] <String>] [[-SystemPrompt] <String>] [[-AppendSystemPrompt] <String>]
 [[-SystemPromptPath] <String[]>] [[-InstructionPath] <String[]>] [[-InstructionRoot] <String[]>]
 [[-SkillPath] <String[]>] [-IncludeSkillBody] [[-Attachment] <String[]>] [[-Image] <String[]>]
 [[-History] <Object[]>] [[-Model] <String>] [[-MaxContextWindowTokens] <Int32>] [[-Mode] <String>]
 [[-Tool] <String[]>] [[-ExcludeTool] <String[]>] [-DeferredToolLoading] [-DisableBrowsing]
 [-DisableFileAccess] [-DisableTerminal] [-DisableUserPrompts] [-DisableTodoList] [-DisableUserTools]
 [-DisableMcp] [<CommonParameters>]

DESCRIPTION

Composes exactly what Invoke-Shp would put in front of the model for the options given - the built-in system content, the caller's instructions, the Skill and Instruction catalogs, the offered Tool schemas, inlined attachments, the Session chat, the prompt and any Tool results already in the conversation - and attributes the estimated token cost of each to its own row.

It answers the question a context window actually raises: not "how big is this" but "what is taking up the room". A Turn that overflows is usually paying for something the caller did not realise was there - a registered Tool schema nobody calls, an instruction file that grew, a Tool result from six iterations ago - and a single total cannot show any of that.

NOTHING is sent. No provider call, no credential, no token exchange, no Server contact. The composition uses the same private seams the real Turn uses (New-ShpToolOffer, New-ShpSystemContent), so the schemas and the system text reported are the ones that would be sent, not a second implementation's idea of them.

Every Known row is measured with the SAME estimator, ConvertTo-ShpTokenCount, and the total is the sum of those rows, so the breakdown and the total cannot disagree. A contribution that cannot be sized locally is reported with a null count and a stated reason instead of a zero: an image is tokenized by the provider, and a Skill body has not been loaded until the model asks for it. Provider-side framing overhead is not modelled, and the service's reported usage stays authoritative.

With -DeferredToolLoading the report shows the offer as the Turn would make it - eligible User and MCP schemas withheld, search_tools in their place - and states separately how many schemas were withheld and what they would have cost. That is the measurement that makes Deferred Tool loading a decision rather than a guess.

EXAMPLES

EXAMPLE 1

Get-ShpContextReport -Prompt 'Summarise the build failure.'

Shows where the estimated Context tokens of that call would go.

EXAMPLE 2

Get-ShpContextReport -Prompt $prompt -DeferredToolLoading

Shows the same call with dynamic Tool schemas withheld, and states how many schemas were withheld and what they would have cost.

EXAMPLE 3

(Get-ShpContextReport -Prompt $prompt).Sources | Sort-Object EstimatedTokens -Descending

Ranks the sources so the largest contributor is first.

PARAMETERS

-AppendSystemPrompt

Extra inline guidance appended after any other instruction.

Type: String
Parameter Sets: (All)
Aliases:

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

-Attachment

Files that would be attached. Text is inlined and accounted; a binary contributes its manifest entry; an image is reported as unknown.

Type: String[]
Parameter Sets: (All)
Aliases:

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

-DeferredToolLoading

Report the offer as a Deferred Tool loading Turn would make it.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-DisableBrowsing

Account the offer without fetch_url.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-DisableFileAccess

Account the offer without the file tools.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-DisableMcp

Account the offer without MCP tools.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-DisableTerminal

Account the offer without the Terminal tool.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-DisableTodoList

Account the offer without manage_todo_list.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-DisableUserPrompts

Account the offer without ask_user.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-DisableUserTools

Account the offer without registered User tools.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-ExcludeTool

Account the offer without these Tool names.

Type: String[]
Parameter Sets: (All)
Aliases:

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

-History

Account this conversation instead of the Session chat, in the same shape Invoke-Shp -History accepts. A tool-role entry is attributed to Tool results rather than to Session chat.

Type: Object[]
Parameter Sets: (All)
Aliases:

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

-Image

Images that would ride in the user message. Reported as unknown, because the provider tokenizes them.

Type: String[]
Parameter Sets: (All)
Aliases:

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

-IncludeSkillBody

Also read and account every discovered Skill body, answering what loading all of them would cost. Off by default, because a body is not in the Context until the model calls load_skill and reporting it as if it were would overstate the request.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-InstructionPath

One or more instruction files whose bodies are injected.

Type: String[]
Parameter Sets: (All)
Aliases:

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

-InstructionRoot

One or more folders scanned for instruction files offered by name.

Type: String[]
Parameter Sets: (All)
Aliases:

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

-MaxContextWindowTokens

Context budget to report against; 0 reports no remaining figure. Omit it to resolve the budget the way a Turn would.

Type: Int32
Parameter Sets: (All)
Aliases:

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

-Mode

Default or Plan, which narrows the offered Tool schemas.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 13
Default value: Default
Accept pipeline input: False
Accept wildcard characters: False

-Model

The model the budget is resolved for. Defaults to the Session default.

Type: String
Parameter Sets: (All)
Aliases:

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

-Prompt

The prompt that would be sent. Optional: a report with no prompt sizes everything that surrounds one.

Type: String
Parameter Sets: (All)
Aliases:

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

-SkillPath

One or more folders scanned for Skills offered by name.

Type: String[]
Parameter Sets: (All)
Aliases:

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

-SystemPrompt

Inline system prompt, as Invoke-Shp would apply it.

Type: String
Parameter Sets: (All)
Aliases:

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

-SystemPromptPath

One or more system-prompt files, front-matter stripped.

Type: String[]
Parameter Sets: (All)
Aliases:

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

-Tool

Account only these Tool names, as Invoke-Shp -Tool would.

Type: String[]
Parameter Sets: (All)
Aliases:

Required: False
Position: 14
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.ContextReport: Estimator, EstimatedTokens, Sources (one

ShellPilot.ContextSource per accounted source), Unknown, the resolved

Context budget and what is left, and the Deferred Tool loading figures.

NOTES

RELATED LINKS

Invoke-Shp

Compress-ShpChat

ConvertTo-ShpTokenCount