# Understanding the Role of the @magnitudedev/sdk Package in Magnitude

> Discover how the @magnitudedev/sdk package acts as a typed bridge for Magnitude, managing RPCs, AI provider interactions, and protocol types for client applications.

- Repository: [Magnitude/magnitude](https://github.com/magnitudedev/magnitude)
- Tags: api-reference
- Published: 2026-09-05

---

**The `@magnitudedev/sdk` package serves as the primary typed bridge between client-side applications and Magnitude's ACN daemon, encapsulating RPC lifecycle management, AI provider interactions, and protocol type re-exports into a single, stable dependency.**

The `@magnitudedev/sdk` package sits at the core of the `magnitudedev/magnitude` repository, acting as the central abstraction layer that shields CLI and web front-ends from the complexity of underlying infrastructure. According to architectural documentation in [`AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/AGENTS.md) (line 14), this package enables higher-level code to interact with the ACN daemon and AI model providers without directly depending on low-level implementation packages such as `acn`, `agent`, or `providers`.

## Core Responsibilities of the SDK

The architecture of `@magnitudedev/sdk` revolves around three primary domains that collectively provide a type-safe, versioned API for downstream developers.

### Typed RPC Client and Daemon Lifecycle Management

At the infrastructure layer, the SDK manages the **ACN daemon** process through the `DaemonSpawner` class and the `makeLocalAcnInstanceManager` factory. These components, implemented in [`packages/sdk/src/acn-jit/local-acn-instance-manager.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/acn-jit/local-acn-instance-manager.ts) and [`packages/sdk/src/acn-jit/acn-recovering-client.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/acn-jit/acn-recovering-client.ts), handle binary resolution, process spawning, and resilient RPC reconnection logic.

The `DaemonSpawner.start()` method encapsulates the complexity of process management and transport handling, returning an Effect-TS-based client that monitors daemon health. This ensures that upstream packages like `@magnitudedev/client-common` never interact directly with raw process handles or transport sockets, as enforced by the dependency rules in [`AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/AGENTS.md) (line 12).

### Provider Client Surface for AI Inference

The **ProviderClient** API, defined in [`packages/sdk/src/provider-client.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/provider-client.ts) and exported from [`packages/sdk/src/index.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/index.ts) (lines 55-71), serves as the sole entry point for agent components to interact with AI model providers. The `createProviderClient()` function instantiates a type-safe client that bundles model discovery, inference execution, and utility endpoints into a consistent interface.

```typescript
import { ProviderClient, createProviderClient } from "@magnitudedev/sdk";

const client: ProviderClient = createProviderClient({
  apiKey: process.env.MAGNITUDE_API_KEY,
  endpoint: "https://api.magnitude.dev",
});

const models = await client.listModels();
const result = await client.invokeModel({
  modelId: "claude-2",
  prompt: "Explain the role of the SDK package.",
});

```

This encapsulation ensures consistent error handling and request formatting across all provider interactions, preventing client code from managing raw HTTP contracts or provider-specific authentication schemes.

### ACN Protocol Type Re-exports

To maintain a clean public surface and enforce separation of concerns, the SDK re-exports all **ACN wire contracts**—including schemas, operation groups, and error types—from [`packages/sdk/src/index.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/index.ts) (line 94). This architectural decision allows consumers to import types like `DisplayStateSchema` directly from `@magnitudedev/sdk` without adding direct dependencies on the internal `acn-protocol` package.

```typescript
import { DisplayStateSchema } from "@magnitudedev/sdk";

type DisplayState = typeof DisplayStateSchema.Type;

```

By centralizing these exports, the SDK keeps dependency graphs clean and ensures that breaking changes in the underlying protocol can be managed through SDK versioning rather than forcing updates across multiple consumer packages.

## Key Implementation Files

The functionality of `@magnitudedev/sdk` is distributed across specific files in the `packages/sdk/src/` directory:

- **[`packages/sdk/src/index.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/index.ts)**: The central export barrel defining the public API surface, including `ProviderClient`, ACN type re-exports, tracing utilities, and version metadata.
- **[`packages/sdk/src/provider-client.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/provider-client.ts)**: Implements model catalog retrieval, inference calls, and utility service endpoints.
- **[`packages/sdk/src/acn-jit/acn-recovering-client.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/acn-jit/acn-recovering-client.ts)**: Handles resilient RPC communication with the ACN daemon, implementing reconnection and recovery semantics.
- **[`packages/sdk/src/acn-jit/local-acn-instance-manager.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/acn-jit/local-acn-instance-manager.ts)**: Manages local ACN daemon lifecycle, including binary path resolution and graceful shutdown supervision.
- **[`packages/sdk/src/tracing.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/tracing.ts)**: Provides tracing utilities that integrate with the Motel OpenTelemetry collector.
- **[`packages/sdk/src/version.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/version.ts)**: Exposes SDK version metadata used for runtime compatibility checks between client and daemon.

## Manual Daemon Management

While typically invoked internally by higher-level clients, developers can manually spawn the ACN daemon using the SDK's lower-level utilities:

```typescript
import { DaemonSpawner, makeLocalAcnInstanceManager } from "@magnitudedev/sdk";

const acnManager = makeLocalAcnInstanceManager({
  binaryPath: "/usr/local/bin/acn",
  dataDir: "~/.magnitude/acn",
});

await DaemonSpawner.start(acnManager);

```

This pattern launches the daemon with proper tracing integration and process supervision, ensuring that the RPC client maintains connection resilience even across daemon restarts.

## Summary

- The `@magnitudedev/sdk` package functions as the **typed abstraction layer** between client applications and Magnitude's ACN infrastructure.
- It encapsulates **daemon lifecycle management** through `DaemonSpawner` and `makeLocalAcnInstanceManager`, hiding process complexity from upstream code.
- The **ProviderClient** API provides a unified, type-safe interface for model discovery (`listModels()`) and inference execution (`invokeModel()`).
- All **ACN protocol types** are re-exported from a single entry point, preventing direct dependencies on internal packages like `acn-protocol`.
- Client applications depend only on `@magnitudedev/sdk` and `@magnitudedev/client-common`, never requiring imports from `acn`, `agent`, or `providers` packages directly.

## Frequently Asked Questions

### What is the relationship between @magnitudedev/sdk and the ACN daemon?

The `@magnitudedev/sdk` package implements the **RPC protocol** used to communicate with the ACN daemon. It provides the `DaemonSpawner` class and `makeLocalAcnInstanceManager` function to start, monitor, and shut down the daemon process, effectively acting as the sole bridge between client code and the low-level ACN infrastructure as documented in [`AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/AGENTS.md) (line 14).

### How does the ProviderClient interface with AI models?

The **ProviderClient** exposes a type-safe API for AI model interaction, bundling model catalog discovery, inference invocation, and utility endpoints behind consistent methods like `listModels()` and `invokeModel()`. This client is created via `createProviderClient()` and serves as the only surface area for agents to interact with AI providers according to [`packages/sdk/src/index.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/index.ts) (lines 55-71).

### Why are ACN protocol types re-exported from the SDK?

Re-exporting types from [`packages/sdk/src/index.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/src/index.ts) (line 94) maintains a **stable public API** while allowing the internal `acn-protocol` package to evolve independently. Consumers import schemas like `DisplayStateSchema` directly from `@magnitudedev/sdk`, ensuring dependency graphs remain clean and versioned compatibility checks remain centralized.

### Can the SDK be used to manually spawn the ACN daemon?

Yes, while typically invoked internally, developers can manually spawn the daemon using `makeLocalAcnInstanceManager()` to configure binary paths and data directories, followed by `DaemonSpawner.start()` to launch the process with proper tracing and supervision as implemented in `packages/sdk/src/acn-jit/`.