octet

Documentation Development

Extension API 0.4

Current extension API 0.4 and retained wire reference.

API 0.4 is the current working-tree extension API version, using the feature-negotiated JSON-RPC wire retained from API 0.2. Extensions add tools and bounded host-shaped integrations to a small coding host; this is not a promise of Pi execution parity or a general extension platform. Exact host offers and frontend bindings determine product availability. This reference targets octet 0.8.0; native publication does not publish SDK registries.

Version policy#

API Status Wire Runtime Installable bundles
0.1 frozen legacy-json-rpc supported unavailable
0.2 supported legacy-json-rpc supported supported
0.3 supported canonical-json-rpc supported supported
0.4 current legacy-json-rpc supported supported

API 0.1 remains frozen at its legacy wire. API 0.2 and 0.3 remain runtime and bundle supported; API 0.4 is current and is the version new extensions must declare. Selection is exact and never silently upgrades a legacy manifest. The tables and canonical models below are generated from the retained API 0.3 schema, not a replacement API 0.4 handshake. For the feature-negotiated wire, including commands, status/presentation, dynamic tools, artifacts, agent_sessions, and conditional approvals, see the protocol reference. Existing runtime contracts, SDKs, and conformance tests remain live; documenting a service does not promise that every product host exposes it. On the canonical wire, required host-offer sets are fixed; optional services are omitted when they cannot be safely bound.

Canonical framing and JSON-RPC envelopes#

This section describes the retained API 0.3 canonical wire. API 0.4 keeps feature-negotiated JSON-RPC framing instead; do not retag canonical messages. Canonical frames are UTF-8 canonical JSON followed by exactly one LF. max_frame_bytes excludes that delimiter. After initialization the selected bound replaces the offered bound atomically for both stdin writes and stdout reads. A frame exactly at the bound is accepted; one byte over terminates the protocol stream.

JSON-RPC envelopes have no unknown fields. Requests require id, method, and params; notifications require method and params but forbid id; responses require a valid non-null ID and exactly one of result or error. Error-response code/message pairs must exactly match the generated API 0.3 error table. IDs are bounded strings or non-negative portable integers. Duplicate keys, noncanonical whitespace/escapes, malformed UTF-16 surrogate escapes, nonportable numbers, and depth violations are rejected before dispatch.

Bounds#

Name Maximum Negotiated Meaning
max_frame_bytes 1048576 yes Maximum UTF-8 JSON-RPC payload bytes, excluding the line delimiter.
max_concurrent_requests 64 yes Maximum concurrently admitted host-to-extension requests.
max_tools 256 yes Maximum complete tool catalog entries.
max_extension_flags 64 no Maximum manifest-declared CLI flag values delivered during initialization.
max_capabilities 32 no Maximum requested or selected capability names in one contract.
max_methods 64 no Maximum requested or selected method names in one contract.
max_capability_name_bytes 64 no Maximum UTF-8 bytes in one capability name.
max_method_name_bytes 128 no Maximum UTF-8 bytes in one method name.
max_reason_bytes 4096 no Maximum UTF-8 bytes in an inspectable disposition reason.
max_json_depth 32 no Maximum nested JSON container depth for canonical protocol values.
max_portable_json_integer 9007199254740991 no Largest exactly portable JSON integer accepted by canonical encoding.
max_content_parts 256 no Maximum ordered API 0.3 tool-result content parts.
max_tool_name_bytes 128 no Maximum UTF-8 bytes in an API 0.3 tool name.
max_tool_description_bytes 4096 no Maximum UTF-8 bytes in an API 0.3 tool description.
max_json_rpc_id_bytes 256 no Maximum UTF-8 bytes in a string JSON-RPC identifier.
max_migration_items 128 no Maximum source items in one migration adapter category.
max_migration_path_bytes 4096 no Maximum UTF-8 bytes in a migration source-root or source-relative path.
max_migration_name_bytes 128 no Maximum UTF-8 bytes in one migration model, skill, or server name.
max_migration_skill_bytes 131072 no Maximum UTF-8 bytes in one migrated skill payload.
max_migration_command_bytes 4096 no Maximum UTF-8 bytes in one migrated stdio command.
max_migration_argument_bytes 16384 no Maximum UTF-8 bytes in one migrated stdio argument.
max_migration_diagnostic_bytes 4096 no Maximum UTF-8 bytes in one migration diagnostic reason.
max_providers 32 no Maximum live extension-provider declarations across one host registry.
max_provider_models 256 no Maximum live extension-provider model declarations across one host registry.
max_provider_id_bytes 64 no Maximum UTF-8 bytes in an extension provider or model identifier.
max_provider_label_bytes 128 no Maximum UTF-8 bytes in an extension provider or model display label.
max_provider_auth_scopes 32 no Maximum OAuth or credential scopes in one host-policy request.
max_provider_auth_lease_bytes 256 no Maximum UTF-8 bytes in an opaque host-issued authorization lease.
max_provider_stream_event_bytes 65536 no Maximum canonical bytes in one provider stream event payload.
max_provider_stream_events 100000 no Maximum events accepted for one extension-provider stream.
max_session_hook_id_bytes 256 no Maximum UTF-8 bytes in one opaque session-hook binding identifier.
max_theme_id_bytes 128 no Maximum UTF-8 bytes in one host-advertised theme id.
max_bus_topics 128 no Maximum declared topics per session-isolated host bus.
max_bus_peers 64 no Maximum process generations attached to one session-isolated bus.
max_bus_fields 24 no Maximum scalar fields in one declared bus topic.
max_bus_identifier_bytes 64 no Maximum bytes in a bus publisher, topic segment, or field name.
max_bus_topic_bytes 96 no Maximum bytes in one exact bus topic.
max_bus_string_bytes 1024 no Maximum bytes in a bus string or enumeration value.
max_bus_enum_values 32 no Maximum alternatives in one bus enumeration field.
max_bus_message_bytes 8192 no Maximum encoded bus event bytes excluding LF.
max_bus_queue_messages 64 no Maximum queued bus events per subscriber process.
max_bus_queue_bytes 262144 no Maximum queued bus event bytes per subscriber process.
max_bus_subscriptions 16 no Maximum exact-topic subscriptions per process.
max_bus_message_age_ms 30000 no Maximum time a queued bus event may wait before delivery; expired events are discarded.

Capabilities#

Capability Default offer Status Meaning
content_parts required foundation Typed text/media tool-result parts and structured result details.
core required foundation Versioned initialization, explicit errors, bounds, and canonical encoding.
dynamic_tools unavailable deferred Live transactional tool-catalog mutation.
lifecycle_events optional foundation Declared SessionStart/SessionEnd hooks for host-owned session lifecycle cleanup.
migration.adapter.v1 optional foundation Bounded read-only setup detection and import conversion for host-owned migration ingestion.
provider_auth optional foundation Explicit host-policy OAuth and credential authorization requests with opaque leases only.
provider_catalog optional foundation Lifecycle-owned registration of secret-free extension provider and model catalogs.
provider_stream optional foundation Bounded host-mediated inference stream proxying for registered extension models.
request_cancellation required foundation Cooperative cancellation with explicit terminal disposition.
session_lifecycle optional foundation Bounded extension requests to create, fork, switch, or reload a host session.
tool_call required foundation Bounded host-to-extension model tool invocation.
theme_selection optional foundation Host-mediated, extension-namespaced presentation theme selection over host-resolved non-widening themes.
event_bus optional foundation Optional session-isolated bus. Selection MUST include bus/lifecycle; subscriptions also require bus/event. No compatibility claim for earlier draft bus contracts.

Methods and terminal semantics#

Method Direction Params Result Terminal Notification Status
$/cancelRequest bidirectional CancelRequestParams CancelRequestResult original_request_cancelled yes foundation
context/collect host_to_extension — — deferred no deferred
hook/run host_to_extension SessionHookParams SessionHookResult result_or_error no foundation
initialize host_to_extension InitializeRequest InitializeResponse initialized no foundation
migration/detect host_to_extension MigrationDetectParams MigrationDetectResult result_or_error no foundation
migration/import host_to_extension MigrationImportParams MigrationImportResult result_or_error no foundation
provider/auth/request extension_to_host ProviderAuthorizationRequest ProviderAuthorizationResult result_or_error no foundation
provider/auth/revoke extension_to_host ProviderAuthorizationRequest ProviderAuthorizationResult result_or_error no foundation
provider/cancel host_to_extension ProviderStreamCancelParams — stream_event yes foundation
provider/event extension_to_host ProviderStreamEvent — stream_event yes foundation
provider/stream host_to_extension ProviderStreamRequest ProviderStreamAccepted result_or_error no foundation
providers/complete extension_to_host ProviderCatalogCompleteParams — catalog_complete yes foundation
providers/register extension_to_host ProviderRegisterParams ProviderCatalogResult result_or_error no foundation
providers/unregister extension_to_host ProviderUnregisterParams ProviderCatalogResult result_or_error no foundation
providers/update extension_to_host ProviderUpdateParams ProviderCatalogResult result_or_error no foundation
session/create extension_to_host SessionCreateParams SessionLifecycleResult result_or_error no foundation
session/fork extension_to_host SessionForkParams SessionLifecycleResult result_or_error no foundation
session/reload extension_to_host SessionReloadParams SessionLifecycleResult result_or_error no foundation
session/switch extension_to_host SessionSwitchParams SessionLifecycleResult result_or_error no foundation
shutdown host_to_extension ShutdownParams ShutdownResult shutdown no foundation
tool/call host_to_extension ToolCallParams ToolCallResult result_or_error no foundation
tools/register extension_to_host — — deferred no deferred
tools/unregister extension_to_host — — deferred no deferred
theme/select extension_to_host ThemeSelectParams ThemeSelectResult result_or_error no foundation
bus/declare extension_to_host BusDeclareParams BusAck result_or_error no foundation
bus/subscribe extension_to_host BusTopicParams BusSubscribeResult result_or_error no foundation
bus/unsubscribe extension_to_host BusTopicParams BusAck result_or_error no foundation
bus/publish extension_to_host BusPublishParams BusPublishResult result_or_error no foundation
bus/event host_to_extension BusEventParams — stream_event yes foundation
bus/lifecycle host_to_extension BusLifecycleParams — stream_event yes foundation

Deferred capabilities and methods remain unavailable on this canonical API 0.3 wire; only the listed foundation methods and capabilities may be negotiated there. In particular, this does not withdraw dynamic tools used by MCP or other retained API 0.2/0.4 services.

Errors#

Name Code Message Meaning
parse_error -32700 parse error Invalid JSON was received.
invalid_request -32600 invalid request The JSON-RPC envelope is invalid.
unknown_method -32601 unknown or unnegotiated method The method is absent from the negotiated API 0.3 contract.
invalid_params -32602 invalid params Parameters violate a canonical wire type or bound.
internal_error -32603 internal error The implementation could not complete a valid request.
version_mismatch -32010 extension API version mismatch The peer did not select exactly API 0.3 and this wire cannot be adapted.
capability_mismatch -32011 extension capability mismatch A required capability or method is missing, duplicated, unknown, or not offered.
resource_exhausted -32012 extension resource exhausted A declared aggregate or per-contract bound was exhausted.
request_cancelled -32800 request cancelled Cooperative cancellation won the terminal race.

Dispositions#

Kind Reason Meaning
continue optional Continue the operation without a veto.
deny required Deny an interceptable operation with an inspectable reason.
defer required Defer a supported operation until a host-owned boundary resolves.

Generated wire models#

ProtocolLimits#

Negotiated maxima selected by the extension and capped by the host.

Field Type Presence Nullable
max_frame_bytes integer required no
max_concurrent_requests integer required no
max_tools integer required no

ContractOffer#

Host offer for the API 0.3 capability and method contract.

Field Type Presence Nullable
schema string required no
encoding string required no
required_capabilities string[] required no
optional_capabilities string[] required no
required_methods string[] required no
optional_methods string[] required no
limits ProtocolLimits required no

ContractSelection#

Extension selection from one API 0.3 contract offer.

Field Type Presence Nullable
schema string required no
encoding string required no
capabilities string[] required no
methods string[] required no
limits ProtocolLimits required no

ToolDefinition#

A complete API 0.3 model tool definition returned at initialization.

Field Type Presence Nullable
name string required no
description string required no
parameters json required no
output_schema json optional no

ContentPart#

One ordered, typed API 0.3 tool-result content part.

Variant Wire tag Status Fields
Text text foundation text: string
Image image deferred artifact_id: string, mime_type: string, alt: string
Audio audio deferred artifact_id: string, mime_type: string, transcript: string

ToolCallParams#

Host-to-extension bounded API 0.3 tool invocation parameters.

Field Type Presence Nullable
name string required no
arguments json required no
context json required no

ToolCallResult#

Terminal successful API 0.3 tool-call result; failures use the generated JSON-RPC error envelope.

Field Type Presence Nullable
content ContentPart[] required no
is_error boolean required no
metadata json required yes
structured_content json optional yes

SessionBinding#

Opaque, host-owned session and extension-generation identity for one declared session-hook binding.

Field Type Presence Nullable
session_id string required no
extension_instance_id string required no
process_generation integer required no

SessionStart#

Sanitized payload delivered once when an eligible declared session-hook binding becomes active.

Field Type Presence Nullable
binding SessionBinding required no

SessionEnd#

Sanitized terminal payload delivered once when an eligible declared session-hook binding settles.

Field Type Presence Nullable
binding SessionBinding required no
outcome string required no
reason string required no
duration_ms integer required no

SessionHookParams#

Typed host-to-extension parameters for one declared session lifecycle hook; no mutable session state is exposed.

Variant Wire tag Status Fields
SessionStart session_start foundation payload: SessionStart
SessionEnd session_end foundation payload: SessionEnd

SessionHookResult#

Terminal result for a declared session hook. Non-continue dispositions are recorded but never veto host lifecycle ownership.

Field Type Presence Nullable
disposition Disposition required no

CancelRequestParams#

Idempotent cancellation notification parameters for an active request.

Field Type Presence Nullable
id rpc_id required no
reason string optional no

CancelRequestResult#

The terminal cancellation fact attached to the original request outcome.

Field Type Presence Nullable
terminal string required no
reason string optional no

SessionCreateParams#

Empty parameters for creating one durable host session without switching to it.

Field Type Presence Nullable

SessionForkParams#

Empty parameters for forking the active host session at its current durable head without switching to it.

Field Type Presence Nullable

SessionSwitchParams#

Bounded opaque identifier of a session in the active workspace to make active.

Field Type Presence Nullable
session_id string required no

SessionReloadParams#

Empty parameters for reopening the active host session from disk.

Field Type Presence Nullable

SessionLifecycleResult#

Terminal successful session-lifecycle result containing the affected session identifier.

Field Type Presence Nullable
session_id string required no

ShutdownParams#

Empty graceful-shutdown parameters; unknown fields are rejected.

Field Type Presence Nullable

ShutdownResult#

Terminal graceful-shutdown acknowledgement.

Field Type Presence Nullable
terminal string required no

InitializeFlagValue#

One host-parsed value for a manifest-declared extension CLI flag.

Field Type Presence Nullable
name string required no
value json required no

InitializeRequest#

Canonical API 0.3 initialize parameters. Host-owned metadata values remain explicitly opaque JSON boundaries.

Field Type Presence Nullable
api_version string required no
octet_version string required no
extension json required no
workspace string required no
capabilities json required no
contributes json required no
flag_values InitializeFlagValue[] required no
host json required no
contract ContractOffer required no

InitializeResponse#

Canonical API 0.3 initialize result with the complete selected tool catalog.

Field Type Presence Nullable
api_version string required no
tools ToolDefinition[] required no
contract ContractSelection required no

MigrationDiagnostic#

A bounded non-secret diagnostic emitted while a migration adapter reads a source setup.

Field Type Presence Nullable
path string required no
severity string required no
reason string required no

MigrationDetectParams#

Host-authorized source root for read-only migration detection.

Field Type Presence Nullable
source_root string required no

MigrationDetectResult#

Bounded result of read-only migration source detection. Config paths are source-relative.

Field Type Presence Nullable
detected boolean required no
config_paths string[] required no
diagnostics MigrationDiagnostic[] required no

MigrationImportParams#

Host-authorized source root and previously detected source-relative config paths for read-only conversion.

Field Type Presence Nullable
source_root string required no
config_paths string[] required no

MigrationModel#

A non-secret source model selection with its source-relative provenance path.

Field Type Presence Nullable
path string required no
provider string required no
model string required no

MigrationSkill#

A bounded source skill payload with its source-relative provenance path.

Field Type Presence Nullable
path string required no
name string required no
content string required no

MigrationMcpServer#

A non-secret local stdio MCP declaration. Environment variables, headers, credentials, and working directories are intentionally absent.

Field Type Presence Nullable
path string required no
name string required no
command string required no
args string[] required no

MigrationImportResult#

Bounded typed migration conversion. The adapter never returns credentials, environment values, headers, or permission grants.

Field Type Presence Nullable
models MigrationModel[] required no
skills MigrationSkill[] required no
mcp_servers MigrationMcpServer[] required no
diagnostics MigrationDiagnostic[] required no

ErrorObject#

Bounded JSON-RPC error object using an API 0.3 error-table code. Its data field preserves absent versus explicit null.

Field Type Presence Nullable
code signed_integer required no
message string required no
data json optional yes

Disposition#

Explicit API 0.3 operation disposition. Reason is optional but never nullable when present.

Field Type Presence Nullable
kind disposition required no
reason string optional no

JsonRpcRequest#

Strict JSON-RPC 2.0 request envelope.

Field Type Presence Nullable
jsonrpc string required no
id rpc_id required no
method string required no
params json required no

JsonRpcNotification#

Strict JSON-RPC 2.0 notification envelope.

Field Type Presence Nullable
jsonrpc string required no
method string required no
params json required no

JsonRpcSuccessResponse#

Strict JSON-RPC 2.0 successful response envelope.

Field Type Presence Nullable
jsonrpc string required no
id rpc_id required no
result json required no

JsonRpcErrorResponse#

Strict JSON-RPC 2.0 error response envelope.

Field Type Presence Nullable
jsonrpc string required no
id rpc_id required no
error ErrorObject required no

ProviderAuthRequirement#

Secret-free authentication class requested by an extension provider. Credential values and authorization URLs are never protocol fields.

Field Type Presence Nullable
kind string required no
subject string optional no
scopes string[] optional no

ProviderDefinition#

One secret-free provider declaration owned by the current extension process generation.

Field Type Presence Nullable
id string required no
label string required no
auth ProviderAuthRequirement required no

ProviderModelCapabilities#

Capability subset advertised for a provider-owned model. Media and endpoint configuration remain host policy.

Field Type Presence Nullable
tools boolean required no
parallel_tool_calls boolean required no
structured_output boolean required no
reasoning boolean required no

ProviderModelDefinition#

A model in a provider-owned catalog. It contains no endpoint, header, credential, or URL material.

Field Type Presence Nullable
id string required no
api_name string required no
protocol string required no
context_window integer required no
max_output_tokens integer required no
capabilities ProviderModelCapabilities required no
display_name string optional no

ProviderRegisterParams#

Atomic initial registration of one provider and its complete current model set.

Field Type Presence Nullable
provider ProviderDefinition required no
models ProviderModelDefinition[] required no

ProviderUpdateParams#

Atomic replacement of one owned provider and its complete current model set.

Field Type Presence Nullable
provider ProviderDefinition required no
models ProviderModelDefinition[] required no

ProviderUnregisterParams#

Removal of a provider owned by the current extension process generation.

Field Type Presence Nullable
provider_id string required no

ProviderCatalogCompleteParams#

Idempotent empty notification emitted after an extension has settled its complete initial provider-registration batch, including an empty catalog. Later catalog mutations remain permitted.

Field Type Presence Nullable

ProviderCatalogResult#

Acknowledgement of an atomic provider catalog mutation. IDs are inspectable only; no secret data is retained.

Field Type Presence Nullable
revision integer required no
provider_ids string[] required no
model_ids string[] required no

ProviderStreamRequest#

Host-to-extension inference request using canonical request JSON and an optional opaque host authorization lease.

Field Type Presence Nullable
stream_id string required no
provider_id string required no
model_id string required no
request json required no
authorization_lease string optional no

ProviderStreamAccepted#

Explicit acceptance fact for a provider stream. Acceptance ambiguity never authorizes an automatic replay.

Field Type Presence Nullable
stream_id string required no
accepted boolean required no
reason string optional no

ProviderStreamEvent#

One ordered, bounded canonical provider stream event. Payload shape is selected by kind and decoded by the host.

Field Type Presence Nullable
stream_id string required no
sequence integer required no
kind string required no
payload json required no

ProviderStreamCancelParams#

Best-effort cancellation notification for an accepted provider stream.

Field Type Presence Nullable
stream_id string required no
reason string optional no

ProviderAuthorizationRequest#

Explicit extension request for host-policy authorization. It never carries credential values, URLs, or callback endpoints.

Field Type Presence Nullable
provider_id string required no
action string required no
interactive boolean required no
scopes string[] optional no

ProviderAuthorizationResult#

Host-policy authorization state and an optional opaque, non-secret request-scoped lease.

Field Type Presence Nullable
status string required no
lease string optional no

ThemeSelectParams#

Bounded extension-scoped theme selection request. Scope is fixed to the requesting extension so a selection can never widen project trust.

Field Type Presence Nullable
namespace string required no
theme_id string required no
role string required no
scope string required no

ThemeSelectResult#

Terminal host decision for one theme selection. Only the host names a resolved non-widening theme id.

Field Type Presence Nullable
status string required no
theme_id string optional no
reason string optional no

BusFieldSpec#

One scalar-only bus field. Host runtime additionally screens names, values and conditional bounds.

Field Type Presence Nullable
name string required no
kind string required no
required boolean required no
max_bytes integer required no
values string[] required no
minimum signed_integer optional no
maximum signed_integer optional no

BusDeclareParams#

Declare one immutable typed topic owned by the host-derived requesting process principal.

Field Type Presence Nullable
binding_id string required no
topic string required no
fields BusFieldSpec[] required no

BusTopicParams#

Exact topic interest. Subscribe explicitly acknowledges pending interest or active subscription; unknown topics are never active.

Field Type Presence Nullable
binding_id string required no
topic string required no

BusAck#

Binding-scoped successful declaration or unsubscribe acknowledgement.

Field Type Presence Nullable
binding_id string required no

BusPublishParams#

Typed inert payload; publisher identity, generation, sequence and time are host-owned.

Field Type Presence Nullable
binding_id string required no
topic string required no
payload json required no

BusPublishResult#

Host-owned monotonic sequence of an atomically admitted publication.

Field Type Presence Nullable
binding_id string required no
sequence integer required no
published_at_ms integer required no

BusEventParams#

In-memory event delivered only to a subscribed process of this host session.

Field Type Presence Nullable
binding_id string required no
topic string required no
publisher string required no
publisher_instance_id string required no
process_generation integer required no
sequence integer required no
published_at_ms integer required no
payload json required no

BusSubscribeResult#

Explicit bounded interest admission. Pending is not an active subscription; activation requires a new subscribe ACK with host provenance.

Variant Wire tag Status Fields
Pending pending foundation binding_id: string, topic_revision: integer
Active active foundation binding_id: string, topic_revision: integer, publisher_instance_id: string, process_generation: integer

BusLifecycleParams#

Mandatory negotiated bus control notification. Monotonic host revisions order bindings and exact-topic availability; no authority or publication replay.

Variant Wire tag Status Fields
Binding binding foundation binding_id: string, binding_revision: integer
TopicAvailable topic_available foundation binding_id: string, topic: string, topic_revision: integer, publisher_instance_id: string, process_generation: integer
TopicUnavailable topic_unavailable foundation binding_id: string, topic: string, topic_revision: integer, publisher_instance_id: string, process_generation: integer

Generated artifacts and conformance#

This live schema generates Rust, Python, TypeScript ESM/runtime declarations, canonical golden fixtures, independent hostile negative fixtures, and this reference. Keep generation and conformance checks when qualifying the bounded authoring path; these artifacts are not archived parity scaffolding. Optional nullable fields preserve absent versus explicit null; optional non-null fields reject explicit null in all three SDKs.

console
python3 scripts/generate-extension-api-v03.py --check

The TypeScript package exports ESM runtime at @skaft-software/octet-extension-api-v03 and declarations without registry dependencies. Do not hand-edit generated artifacts.