Browse documentation
Hosted Pi compatibility profile
The versioned Pi 0.83 extension surface targeted by Salambo's hosted runtime.
View MarkdownThis page describes the canonical pi-0.83-hosted-v1 target contract. It is the shared source for Depot validation, CLI diagnostics, sandbox behavior, and public compatibility documentation.
This profile is the authoritative hosted extension contract. The acceptance suite verifies its server-safe APIs, lifecycle hooks, TypeScript build path, multiple-extension composition, cancellation, and durable follow-up behavior.
Status meanings
| Status | Meaning |
|---|---|
| Supported | Behavior matches upstream Pi. |
| Hosted semantics | The capability is available through a documented server-safe behavior. |
| Local only | The capability belongs to the interactive Pi client and is accepted only for local use. |
| Unsupported | Deployment must reject the capability with a stable diagnostic. |
Extension API
| Capability | Status | Hosted behavior | Owner |
|---|---|---|---|
on | Hosted semantics | Registers lifecycle handlers on the session-scoped extension host. | SAL-377 |
registerTool | Hosted semantics | Registers a sandbox-owned tool that the worker invokes through the authenticated sidecar boundary. | SAL-377 |
registerCommand | Local only | Slash commands require an interactive Pi command surface that hosted entry points do not expose. | Profile |
registerShortcut | Local only | Keyboard shortcuts belong to the interactive terminal client. | Profile |
registerFlag | Local only | CLI flags belong to a local Pi process and are not part of a deployed agent version. | Profile |
getFlag | Local only | Hosted deployments do not expose local Pi CLI flags. | Profile |
registerMessageRenderer | Local only | Terminal message rendering does not affect API, Slack, or Teams output. | Profile |
registerEntryRenderer | Local only | Session-entry rendering belongs to the interactive terminal client. | Profile |
sendMessage | Hosted semantics | Persists non-triggering custom messages through the worker action protocol. Live custom-message steer and follow-up remain unavailable in pi-agent-core. | SAL-380 |
sendUserMessage | Hosted semantics | Queues a user message through the worker-owned session action protocol. | SAL-380 |
appendEntry | Hosted semantics | Appends a JSON-safe custom session entry through worker-owned persistence. | SAL-380 |
setSessionName | Hosted semantics | Updates the durable hosted session name through a worker action. | SAL-380 |
getSessionName | Hosted semantics | Reads the current durable hosted session name from the session projection. | SAL-380 |
setLabel | Unsupported | Entry labels remain disabled until Salambo exposes session-tree navigation. | Profile |
exec | Hosted semantics | Runs commands inside the customer sandbox with platform cancellation and filesystem policy. | SAL-377 |
getActiveTools | Hosted semantics | Reads the active tool set for the current hosted session. | SAL-377 |
getAllTools | Hosted semantics | Reads built-in and extension tool metadata without exposing worker internals. | SAL-377 |
setActiveTools | Hosted semantics | Changes and persists the active tool set through the worker-owned session state. | SAL-380 |
getCommands | Local only | Hosted entry points do not expose the interactive Pi command catalogue. | Profile |
setModel | Hosted semantics | Selects an allowed deployment model and persists it for durable follow-up turns. | SAL-382 |
getThinkingLevel | Hosted semantics | Reads the current hosted-session thinking level. | SAL-382 |
setThinkingLevel | Hosted semantics | Selects a supported thinking level and persists it for durable follow-up turns. | SAL-382 |
registerProvider | Hosted semantics | Registers declarative provider metadata; executable provider code cannot cross into the worker. | SAL-382 |
unregisterProvider | Hosted semantics | Removes a session-scoped declarative provider registration. | SAL-382 |
events | Hosted semantics | Provides a session-scoped event bus with deterministic registration order. | SAL-377 |
Lifecycle events
| Capability | Status | Hosted behavior | Owner |
|---|---|---|---|
project_trust | Local only | Deployment approval is the hosted trust decision; extensions do not prompt at session start. | Profile |
resources_discover | Hosted semantics | Adds artifact-contained skill and prompt paths; themes remain inactive without a TUI. | SAL-379 |
session_start | Hosted semantics | Runs after a hosted session starts, resumes, reloads, or forks. | SAL-379 |
session_info_changed | Hosted semantics | Runs after durable hosted session metadata changes. | SAL-380 |
session_before_switch | Local only | Hosted entry points do not expose arbitrary session-file switching. | Profile |
session_before_fork | Local only | Hosted entry points do not expose interactive session forking. | Profile |
session_before_compact | Hosted semantics | Can cancel or customize compaction before the worker commits the result. | SAL-379 |
session_compact | Hosted semantics | Runs after a hosted compaction result is committed. | SAL-379 |
session_shutdown | Hosted semantics | Runs during bounded sidecar shutdown and sandbox cleanup. | SAL-379 |
session_before_tree | Unsupported | Session-tree navigation is not part of the hosted product. | Profile |
session_tree | Unsupported | Session-tree navigation is not part of the hosted product. | Profile |
context | Hosted semantics | Transforms the JSON-safe model context before a provider turn. | SAL-377 |
before_provider_request | Hosted semantics | Transforms the provider request body before the trusted provider client sends it. | SAL-382 |
before_provider_headers | Hosted semantics | Transforms allowed provider headers without exposing sealed credentials. | SAL-382 |
after_provider_response | Hosted semantics | Observes sanitized provider response metadata after a request. | SAL-382 |
before_agent_start | Hosted semantics | Can add context and adjust model or tools before the agent starts. | SAL-377 |
agent_start | Hosted semantics | Runs when the hosted agent loop starts. | SAL-379 |
agent_end | Hosted semantics | Runs when the hosted agent loop ends. | SAL-379 |
agent_settled | Hosted semantics | Runs after the agent and queued messages settle. | SAL-379 |
turn_start | Hosted semantics | Runs when a hosted model turn starts. | SAL-379 |
turn_end | Hosted semantics | Runs when a hosted model turn ends. | SAL-379 |
message_start | Hosted semantics | Runs when a streamed message starts. | SAL-379 |
message_update | Hosted semantics | Runs for streamed message updates with bounded transport payloads. | SAL-381 |
message_end | Hosted semantics | Runs when a streamed message completes. | SAL-381 |
tool_execution_start | Hosted semantics | Runs before a tool executes. | SAL-379 |
tool_execution_update | Hosted semantics | Runs for bounded tool progress updates. | SAL-381 |
tool_execution_end | Hosted semantics | Runs after a tool completes or fails. | SAL-379 |
model_select | Hosted semantics | Runs after the hosted session selects a model. | SAL-379 |
thinking_level_select | Hosted semantics | Runs after the hosted session selects a thinking level. | SAL-379 |
tool_call | Hosted semantics | Can block or rewrite a tool call before sandbox execution. | SAL-377 |
tool_result | Hosted semantics | Can transform a JSON-safe tool result before it returns to the model. | SAL-377 |
user_bash | Local only | This event represents a command entered by a person in the local Pi terminal. | Profile |
input | Hosted semantics | Can transform or handle input received from an authenticated hosted entry point. | SAL-379 |
Extension context
| Capability | Status | Hosted behavior | Owner |
|---|---|---|---|
ui | Hosted semantics | Exposes the non-interactive UI profile defined below; hasUI remains false. | SAL-377 |
mode | Hosted semantics | Always reports json in the hosted runtime. | SAL-377 |
hasUI | Hosted semantics | Always reports false in the hosted runtime. | SAL-377 |
cwd | Supported | Points to the customer workspace inside the sandbox. | Profile |
sessionManager | Hosted semantics | Provides a read-only hosted session projection without storage authority. | SAL-378 |
modelRegistry | Hosted semantics | Exposes allowed model metadata without provider credentials or mutation authority. | SAL-378 |
model | Hosted semantics | Exposes the selected model metadata without provider credentials. | SAL-378 |
scopedModels | Hosted semantics | Exposes the deployment model allowlist as a read-only snapshot. | SAL-378 |
thinkingLevel | Hosted semantics | Exposes the current hosted-session thinking level. | SAL-378 |
isIdle | Hosted semantics | Reflects the worker-owned session state. | SAL-378 |
isProjectTrusted | Hosted semantics | Returns true only after deployment admission approves the immutable artifact. | SAL-375 |
signal | Hosted semantics | Carries run cancellation into sandbox extension handlers and tools. | SAL-377 |
abort | Hosted semantics | Requests cancellation through the worker instead of terminating trusted processes. | SAL-380 |
hasPendingMessages | Hosted semantics | Reads worker-owned steering and follow-up queue state. | SAL-378 |
shutdown | Hosted semantics | Requests bounded session shutdown through the worker. | SAL-380 |
getContextUsage | Hosted semantics | Returns the sanitized usage estimate for the current hosted model context. | SAL-378 |
compact | Hosted semantics | Requests durable compaction through the worker-owned lifecycle. | SAL-380 |
getSystemPrompt | Hosted semantics | Returns the effective prompt after hosted context projection. | SAL-378 |
Command-only context
| Capability | Status | Hosted behavior | Owner |
|---|---|---|---|
getSystemPromptOptions | Local only | Command-only prompt construction is not exposed by hosted entry points. | Profile |
waitForIdle | Local only | Hosted message queues replace interactive command coordination. | Profile |
newSession | Local only | Session creation is controlled by Salambo entry points and APIs. | Profile |
fork | Local only | Interactive session forking is not exposed by hosted entry points. | Profile |
navigateTree | Unsupported | Session-tree navigation is not part of the hosted product. | Profile |
switchSession | Local only | Hosted entry points address conversations instead of session files. | Profile |
reload | Local only | A new immutable deployment version replaces local extension reload. | Profile |
UI context
| Capability | Status | Hosted behavior | Owner |
|---|---|---|---|
select | Local only | Requires an interactive client dialog. | Profile |
confirm | Local only | Requires an interactive client dialog. | Profile |
input | Local only | Requires an interactive client dialog. | Profile |
notify | Hosted semantics | Emits a sanitized run notification instead of drawing terminal UI. | SAL-377 |
onTerminalInput | Local only | Requires raw terminal input. | Profile |
setStatus | Hosted semantics | Emits a bounded run-status projection instead of updating a terminal footer. | SAL-377 |
setWorkingMessage | Local only | Controls the interactive terminal loader. | Profile |
setWorkingVisible | Local only | Controls the interactive terminal loader. | Profile |
setWorkingIndicator | Local only | Controls the interactive terminal loader. | Profile |
setHiddenThinkingLabel | Local only | Controls interactive terminal rendering. | Profile |
setWidget | Local only | Renders an interactive terminal widget. | Profile |
setFooter | Local only | Renders an interactive terminal footer. | Profile |
setHeader | Local only | Renders an interactive terminal header. | Profile |
setTitle | Local only | Controls the terminal window title. | Profile |
custom | Local only | Renders a custom interactive terminal component. | Profile |
pasteToEditor | Local only | Requires the interactive terminal editor. | Profile |
setEditorText | Local only | Requires the interactive terminal editor. | Profile |
getEditorText | Local only | Requires the interactive terminal editor. | Profile |
editor | Local only | Requires the interactive terminal editor. | Profile |
addAutocompleteProvider | Local only | Extends the interactive terminal editor. | Profile |
setEditorComponent | Local only | Replaces the interactive terminal editor. | Profile |
getEditorComponent | Local only | Reads the interactive terminal editor. | Profile |
theme | Local only | Exposes the interactive terminal theme. | Profile |
getAllThemes | Local only | Lists interactive terminal themes. | Profile |
getTheme | Local only | Reads an interactive terminal theme. | Profile |
setTheme | Local only | Changes the interactive terminal theme. | Profile |
getToolsExpanded | Local only | Reads interactive terminal tool-output state. | Profile |
setToolsExpanded | Local only | Changes interactive terminal tool-output state. | Profile |
Tool definition
| Capability | Status | Hosted behavior | Owner |
|---|---|---|---|
name | Supported | Preserved as the model-facing tool identifier. | Profile |
label | Supported | Preserved as human-readable tool metadata. | Profile |
description | Supported | Preserved in the model tool definition. | Profile |
promptSnippet | Hosted semantics | Added to the hosted system prompt when the tool is active. | SAL-377 |
promptGuidelines | Hosted semantics | Added to the hosted system prompt when the tool is active. | SAL-377 |
parameters | Supported | Preserves the upstream TypeBox schema. | Profile |
constrainedSampling | Hosted semantics | Forwarded only when the selected provider supports constrained sampling. | SAL-377 |
renderShell | Local only | Controls interactive terminal rendering. | Profile |
prepareArguments | Hosted semantics | Runs in the sandbox before parameter validation. | SAL-377 |
executionMode | Hosted semantics | Controls Pi harness scheduling for parallel or sequential tool calls. | SAL-377 |
execute | Hosted semantics | Runs inside the sandbox with cancellation and progress propagation. | SAL-377 |
renderCall | Local only | Renders a tool call in the interactive terminal. | Profile |
renderResult | Local only | Renders a tool result in the interactive terminal. | Profile |
Package forms
| Capability | Status | Hosted behavior | Owner |
|---|---|---|---|
typescriptEntrypoint | Hosted semantics | Depot transpiles TypeScript without applying a Salambo-specific semantic typecheck. | SAL-375 |
javascriptEntrypoint | Supported | ES module JavaScript entrypoints are preserved in the deployment artifact. | Profile |
fileEntrypoint | Supported | A file declared in pi.extensions becomes one extension entrypoint. | Profile |
directoryEntrypoint | Hosted semantics | Depot applies upstream Pi directory discovery rules. | SAL-375 |
globEntrypoint | Hosted semantics | Depot expands upstream Pi glob rules in deterministic lexical order. | SAL-375 |
multipleEntrypoints | Hosted semantics | Depot preserves declared order and stable ordering inside expanded globs. | SAL-375 |
manifestDeclaredResources | Hosted semantics | Depot reads extensions, skills, prompts, and themes from the package.json pi manifest. | SAL-375 |
conventionalResources | Hosted semantics | Depot applies upstream discovery rules when the package has no explicit pi manifest. | SAL-375 |
resourceFilters | Hosted semantics | Depot applies upstream include, exclude, force-include, and force-exclude resource filters. | SAL-375 |
skills | Supported | Package skill directories are copied into the immutable artifact. | Profile |
prompts | Supported | Package prompt directories are copied into the immutable artifact. | Profile |
themes | Local only | Themes only affect the interactive Pi terminal. | Profile |
relativeAssets | Hosted semantics | Depot preserves package-relative layout so import.meta.url resources continue to resolve. | SAL-375 |
npmDependencies | Hosted semantics | Depot resolves declared dependencies and records the exact graph in build provenance. | SAL-375 |
bundledDependencies | Hosted semantics | Depot preserves bundled package dependencies inside the immutable artifact. | SAL-375 |
nestedPackageResources | Hosted semantics | Depot can include explicitly declared resources from bundled package dependencies. | SAL-375 |
lockfiles | Hosted semantics | Depot honors a supported source lockfile and records generated resolution when no lockfile exists. | SAL-375 |
dynamicImports | Hosted semantics | Artifact-local dynamic imports are allowed when Depot can resolve and package their targets. | SAL-375 |
remoteDynamicImports | Unsupported | Runtime downloads and remote module imports violate immutable artifact provenance. | Profile |
nativeModules | Unsupported | The first profile does not run native add-ons or package lifecycle builds. | Profile |
lifecycleScripts | Unsupported | Depot installs third-party dependencies with lifecycle scripts disabled. | Profile |
commonJsEntrypoint | Unsupported | The first profile accepts Pi-compatible ES module entrypoints only. | Profile |
Host package set
These exact packages form the Pi 0.83 profile. Extensions must not bring a second incompatible Pi runtime.
| Package | Version | Status | Hosted behavior |
|---|---|---|---|
@earendil-works/pi-coding-agent | 0.83.0 | Hosted semantics | Provides the official extension API, helpers, and built-in tool definitions. |
@earendil-works/pi-agent-core | 0.83.0 | Supported | Provides the official Pi agent types and message contracts. |
@earendil-works/pi-ai | 0.83.0 | Supported | Provides the official Pi model and provider types. |
@earendil-works/pi-tui | 0.83.0 | Hosted semantics | Imports resolve for package compatibility, but TUI rendering capabilities remain local-only. |
@sinclair/typebox | 0.34.52 | Hosted semantics | Provides the legacy schema import used by compatible published Pi extensions. |
typebox | 1.3.7 | Supported | Provides the schema package used by Pi 0.83 tool definitions. |
Build boundary
Depot owns dependency resolution, transpilation, compatibility analysis, and immutable artifact assembly. It does not execute the extension factory or package lifecycle scripts. It preserves package-relative assets and records the resolved dependency graph. Only the sandbox sidecar executes the extension factory, once per hosted session.
Salambo does not add a stricter TypeScript semantic gate. An extension can use its own compiler and type-check policy. Depot only requires code that can be deterministically assembled for the pinned hosted runtime.
Stable diagnostics
| Code | Severity | Meaning | Next action |
|---|---|---|---|
hosted_pi_profile_version_unsupported | error | The deployment requests a hosted Pi profile version that this runtime does not support. | Select a profile version supported by the target environment. |
hosted_pi_version_incompatible | error | The extension package declares a Pi version range that does not include the profile version. | Use a compatible extension release or update its declared Pi peer range. |
hosted_pi_capability_local_only | warning | The extension uses a Pi capability that only works in an interactive local client. | Guard the local behavior with ctx.hasUI or remove it from the hosted entrypoint. |
hosted_pi_capability_unsupported | error | The extension uses a Pi capability that this hosted profile does not support. | Remove the capability or select a future profile that supports it. |
hosted_pi_entrypoint_invalid | error | A declared extension entrypoint is missing, escapes the package root, or has an unsupported format. | Declare a package-local TypeScript or ES module entrypoint. |
hosted_pi_resource_unsupported | error | The package declares a resource type that the hosted profile does not support. | Remove the resource from the hosted package manifest. |
hosted_pi_native_module_unsupported | error | The package requires a native module that the hosted profile cannot build or load. | Use a JavaScript or WebAssembly alternative. |
hosted_pi_dynamic_import_unsupported | error | A dynamic import cannot be resolved into the immutable deployment artifact. | Use an artifact-local import target that Depot can resolve. |
hosted_pi_lifecycle_script_disabled | error | The package requires an install lifecycle script, but hosted builds disable lifecycle scripts. | Publish prebuilt portable assets or remove the lifecycle dependency. |
hosted_pi_dependency_resolution_failed | error | Depot could not resolve a deterministic dependency graph for the extension package. | Repair the package manifest or lockfile and deploy again. |
Legacy Salambo hook migration
| Legacy hook | Official Pi replacement | Rule |
|---|---|---|
before_provider_payload | before_provider_request | This Salambo-only hook is not part of the official Pi profile and must migrate to before_provider_request. |
model_update | model_select | This Salambo-only hook is not part of the official Pi profile and must migrate to model_select. |
thinking_level_update | thinking_level_select | This Salambo-only hook is not part of the official Pi profile and must migrate to thinking_level_select. |