# Extension Runtime v2 Architecture in DeepSeek-Reasonix: A Technical Deep Dive

> Explore the DeepSeek-Reasonix Extension Runtime v2 architecture. This sidecar-based, full-trust environment isolates plugin code via JSON-RPC for precise event control and UI contributions.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: architecture
- Published: 2026-08-13

---

**DeepSeek-Reasonix Extension Runtime v2 is a sidecar-based, full-trust execution environment that isolates plugin code through JSON-RPC, giving extensions precise, manifest-driven control over event interception, model providers, and UI contributions.**

The Extension Runtime v2 architecture powers how third-party code integrates with DeepSeek-Reasonix. Unlike traditional plugin systems that run inside the host process, this design launches extensions as **separate processes** communicating over a stable, versioned wire protocol. This separation enables deep customization while maintaining predictable security boundaries and clean failure modes.

## Core Components of Extension Runtime v2

### Sidecar Process

The sidecar is the fundamental unit of execution. Each extension runs as an independent OS process launched by the Reasonix host and persists until a **runtime reload** or crash termination.

Key characteristics from the source implementation in [`docs/EXTENSION_PROTOCOL.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/EXTENSION_PROTOCOL.md):

- Starts via `extension/initialize` with a 30-second initialization budget
- Receives session context and host capabilities through `InitializeParams`
- Must respond with `InitializeResult` declaring its supported capabilities
- Shuts down gracefully via `extension/shutdown` or is killed on timeout

The host spawns **up to four sidecars in parallel** during startup, validating that all declared capabilities remain a **subset of the manifest**.

### Reasonix Extension Protocol v2

The wire contract `reasonix.extension.v2` defines how host and sidecar communicate. This JSON-RPC protocol specifies methods, events, limits, and error codes in a frozen, forward-compatible schema.

Generated Go types in [`sdk/go/types_generated.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/sdk/go/types_generated.go) include:

- Method name constants (e.g., `MethodExtensionIntercept`, `MethodProviderStreamOpen`)
- Frame size limits: **8 MiB** per JSON-RPC frame
- Externalization threshold: **64 KiB** for payload offloading
- Content reference chunk size: **256 KiB**

### Manifest v2 Runtime Block

Extensions declare their capabilities statically in [`reasonix-plugin.json`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix-plugin.json). The host only starts sidecars for manifests installed through the plugin flow—project files cannot spawn runtimes.

```typescript
// Example: Declaring a runtime block in reasonix-plugin.json
{
  "apiVersion": "reasonix.io/plugin/v2",
  "manifest": {
    "runtime": {
      "command": "myextension --host $HOST --port $PORT",
      "intercepts": ["input.receive", "permission.decision"],
      "replaces": ["system_prompt"],
      "providers": ["myProvider"],
      "uiActions": ["status"]
    }
  }
}

```

## Interception and Replacement System

Extension Runtime v2 provides **17 hook points** where sidecars can influence host behavior. Each interceptor receives the full payload and returns a decision:

- **`continue`** — Pass through unchanged
- **`block`** — Halt the operation
- **`replace`** — Substitute modified payload

```go
// Example: Responding to an intercept request in a sidecar (Go SDK)
func handleIntercept(ctx context.Context, params extension.InterceptParams) (extension.InterceptResult, error) {
    // Decide to modify the input payload
    newInput := strings.ReplaceAll(string(params.Payload), "foo", "bar")
    return extension.InterceptResult{
        Decision: extension.DecisionReplace,
        Payload:  []byte(newInput),
    }, nil
}

```

Replacement slots enforce **single ownership** with manifest priority ordering. This prevents conflicts when multiple extensions target the same hook point.

## Streaming Model Providers

Extensions can expose new model providers through namespaced identifiers: `plugin/<plugin>/<provider>/<model>`. The streaming protocol follows a strict lifecycle:

1. `extension/provider/stream/open` — Establish stream
2. Chunk transmission — Bounded 8 MiB frames
3. `extension/provider/stream/end` — Clean termination

This design allows extensions to integrate custom inference backends without modifying the host's core model routing.

## Structured UI Contributions

Sidecars publish interface elements via `host/ui/publish`, supporting status entries, cards, forms, and notifications. UI actions follow namespaced identifiers:

```typescript
// Example: Publishing a UI status from the sidecar (JSON‑RPC)
await client.send({
  jsonrpc: "2.0",
  method: "host/ui/publish",
  params: {
    kind: "status",
    surfaceId: "status",
    pluginId: "myextension",
    generation: 3,
    payload: { label: "working", details: "Processing…" }
  }
});

```

Action handlers use the format `/<plugin>:<action>` and are invoked through `extension/ui/action`. The host enforces manifest validation before exposing any UI capabilities.

## Content Externalization and Performance

Large payloads exceeding **64 KiB** are automatically externalized to the host's content store, referenced via `ExternalizedField` structures. This prevents JSON-RPC frame bloat while maintaining data accessibility.

| Limit | Value | Purpose |
|-------|-------|---------|
| Frame size | 8 MiB | Maximum JSON-RPC message |
| Externalization threshold | 64 KiB | Payload offloading trigger |
| Content chunk size | 256 KiB | Incremental large object reads |

These constraints enable deterministic benchmarking through `go test ./internal/extension/... -bench 'Extension|Dispatch'`.

## Runtime Reload and Failure Handling

Extension Runtime v2 implements **atomic generation-based reloading**:

1. New sidecar generation spawns in parallel
2. Session state preservation during transition
3. Traffic cutover on successful initialization
4. Automatic rollback on build failure

Crashed sidecars trigger cancellation of pending RPCs. The host restarts the sidecar only after an idle-time reload, preventing crash loops from destabilizing the session.

## Security Model

The Extension Runtime v2 **full-trust** design grants sidecars substantial privileges:

- Unfiltered environment variable access
- Complete session visibility
- Permission bypass capability

Authorization occurs **only at install/update time**, with the host displaying a `FULL TRUST` warning during `--dry-run` preview. The manifest serves as the capability contract; runtime enforcement validates declared permissions and redacts credentials before UI exposure.

## Implementation Reference

Key files defining the Extension Runtime v2 architecture:

| File | Contents |
|------|----------|
| [`docs/EXTENSIONS.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/EXTENSIONS.md) | Runtime overview, reload semantics, security model |
| [`docs/EXTENSION_PROTOCOL.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/EXTENSION_PROTOCOL.md) | Complete protocol specification (transport, lifecycle, limits) |
| [`sdk/go/types_generated.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/sdk/go/types_generated.go) | Generated DTOs, method constants, frozen limits |
| [`desktop/frontend/src/lib/useController.ts`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/frontend/src/lib/useController.ts) | UI surface management for extension generations |
| [`workers/crash-report/src/diagnostics_v2.ts`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/workers/crash-report/src/diagnostics_v2.ts) | Runtime version tracking for diagnostics |

## Summary

- **Extension Runtime v2** isolates plugins through sidecar processes communicating via JSON-RPC
- **17 interception points** enable fine-grained control over host behavior with single-owner replacement semantics
- **Streaming providers** integrate custom models through namespaced identifiers with bounded 8 MiB frames
- **Atomic reload** preserves session state across generation transitions with automatic failure rollback
- **Full-trust security** delegates authorization to install time, enforcing manifest-based capability validation throughout operation

## Frequently Asked Questions

### How does Extension Runtime v2 differ from traditional plugin architectures?

Traditional plugins typically run inside the host process with sandboxed permissions. Extension Runtime v2 launches **separate OS processes** with full-trust privileges, using JSON-RPC for communication. This separation prevents plugin crashes from destabilizing the host, enables independent resource management, and supports clean hot-reloading without session interruption.

### What happens if a sidecar exceeds the 30-second initialization budget?

The host terminates the sidecar process and marks the extension as failed. Other parallel sidecar initializations continue unaffected. The host will attempt restart only after an idle-time runtime reload, not immediately, to prevent resource exhaustion from repeatedly failing extensions.

### Can multiple extensions replace the same system prompt?

No. Replacement slots enforce **single ownership** with manifest priority determining which extension wins when multiple claim the same slot. This design prevents conflicting modifications and ensures deterministic behavior. Extensions should declare replacement intents explicitly in their manifest's `replaces` array.

### How does payload externalization work for large data transfers?

When a payload exceeds **64 KiB**, the host automatically stores it in a content-addressed blob store and replaces the field with an `ExternalizedField` reference containing the content ID. The sidecar retrieves chunks via content reference methods with **256 KiB** granularity, keeping JSON-RPC frames under the 8 MiB limit while enabling efficient large object handling.