# What Is the acn-protocol Package in Magnitude? RPC Contracts and Service Boundaries

> Discover the acn-protocol package in Magnitude. It defines RPC contracts and service boundaries for SDK-ACN communication, ensuring typed interactions and shared schemas.

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

---

**The acn-protocol package serves as the canonical wire-level contract that governs how the Magnitude SDK communicates with the Agent Control Node (ACN) daemon, defining typed RPC boundaries, shared Effect schemas, and service facades while remaining isolated from direct UI client imports.**

The acn-protocol package in the `magnitudedev/magnitude` repository establishes the foundational communication layer between the Magnitude SDK and the background ACN daemon. It codifies the exact message formats, service interfaces, and recovery policies required for type-safe, resilient remote procedure calls. By isolating these low-level concerns behind a versioned contract, the package enables independent evolution of client SDKs and daemon implementations without breaking cross-version compatibility.

## Defining the RPC Surface with AcnRpc

At the heart of the package lies the **AcnRpc** adapter, which decorates Effect-Query operations with recovery policies and transforms them into callable RPC endpoints. Located in [`packages/acn-protocol/src/boundary/rpc.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn-protocol/src/boundary/rpc.ts) at lines 15-33, this adapter allows the SDK to invoke remote functions on the ACN daemon while ensuring that transient failures are handled according to predefined resilience strategies.

The adapter effectively bridges the gap between local Effect computations and network-bound operations. When the SDK initiates a call, the AcnRpc layer serializes the request, applies transport-level recovery policies, and deserializes responses back into typed Effect structures that the client code can consume safely.

## Exposing Typed Service Boundaries

The package declares every public ACN service—such as **Sessions**, **Projects**, **Models**, and **Display**—within dedicated boundary files. These service definitions are then centrally re-exported from [`packages/acn-protocol/src/boundary/index.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn-protocol/src/boundary/index.ts) at lines 1-18, creating a clean separation between interface and implementation.

This boundary pattern ensures that both the SDK client and the ACN daemon share identical type definitions for all callable operations. When you import `Sessions` or `Projects` from the package, you are importing the typed contract that both sides of the connection must honor, eliminating drift between client expectations and server capabilities.

## Providing Shared Effect Schemas

All data structures that cross the JSON wire boundary are modeled using **Effect Schemas** located in `packages/acn-protocol/src/schemas/*`. These schemas govern the serialization and deserialization of complex domain objects including model state, session definitions, project files, and onboarding data.

For example, [`packages/acn-protocol/src/schemas/model-state.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn-protocol/src/schemas/model-state.ts) defines the exact shape and validation rules for AI model configurations passed between processes. By using Effect's schema system, the package guarantees deterministic encoding and decoding, catching serialization mismatches at the type level before they reach runtime.

## Architectural Isolation from UI Clients

According to [`AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/AGENTS.md) at lines 12-18, the acn-protocol package is explicitly designed to remain invisible to UI client code. Instead of importing directly from `@magnitudedev/acn-protocol`, client applications must consume these capabilities through `@magnitudedev/client-common` or `@magnitudedev/sdk`.

This layering invariant keeps the public API surface stable while allowing the protocol to evolve internally. The SDK acts as a protective facade, exposing only high-level workflows to client code while managing the low-level RPC details internally.

## Implementing the ACN Protocol Contract

### Calling Remote ACN Services from the SDK

To interact with the daemon, you initialize the transport layer and invoke service methods through the AcnRpc adapter:

```typescript
import { AcnRpc } from "@magnitudedev/acn-protocol"
import { Sessions } from "@magnitudedev/acn-protocol"
import { DaemonSpawner } from "@magnitudedev/sdk"

// Spawn the daemon process (handled by the SDK)
const daemon = await DaemonSpawner.start()

// Obtain an RPC client that uses the AcnRpc adapter
const rpc = AcnRpc(daemon.transport)

// Use the generated service façade
const sessionInfo = await Sessions.getSessionInfo(rpc, {
  sessionId: "abc123"
})

// `sessionInfo` is typed according to the schema in
// `src/schemas/session.ts`

```

This pattern ensures that `sessionInfo` returns a value strictly typed according to the schema defined in [`src/schemas/session.ts`](https://github.com/magnitudedev/magnitude/blob/main/src/schemas/session.ts), with all wire-format concerns handled transparently by the protocol layer.

### Implementing ACN Service Handlers in the Daemon

When building a custom ACN daemon, you implement the service contracts defined in the protocol package:

```typescript
import { Sessions } from "@magnitudedev/acn-protocol"
import { Effect } from "effect"

export const SessionsImpl = {
  getSessionInfo: (sessionId) =>
    Effect.succeed({ /* …session data shaped by src/schemas/session.ts… */ })
}

```

The daemon implementation must return Effect values that conform to the exact input/output types specified in the boundary definitions, ensuring runtime compatibility with SDK clients.

### Validating Wire Data with Effect Schemas

For low-level validation of raw payloads before processing, you can invoke the schema decoders directly:

```typescript
import { ModelState } from "@magnitudedev/acn-protocol"

const raw = JSON.parse(receivedPayload)
const validated = ModelState.decode(raw) // throws if payload does not match schema

```

This approach leverages Effect's decoding mechanisms to enforce the contracts defined in `packages/acn-protocol/src/schemas/*`, failing fast on malformed data before it propagates through the system.

## Summary

- **The acn-protocol package** acts as the authoritative wire-level contract between the Magnitude SDK and the ACN daemon, located in the `magnitudedev/magnitude` repository.
- **AcnRpc adapter** in [`packages/acn-protocol/src/boundary/rpc.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn-protocol/src/boundary/rpc.ts) decorates Effect-Query operations with recovery policies and exposes them as callable RPC endpoints.
- **Service boundaries** in [`packages/acn-protocol/src/boundary/index.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn-protocol/src/boundary/index.ts) export typed facades for Sessions, Projects, Models, and other ACN services that both client and daemon share.
- **Effect Schemas** in `packages/acn-protocol/src/schemas/*` provide deterministic serialization guarantees for all data crossing the process boundary.
- **Design constraint** documented in [`AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/AGENTS.md) prevents direct UI client imports, forcing access through the SDK layer to maintain API stability.

## Frequently Asked Questions

### What is the primary purpose of the acn-protocol package in Magnitude?

The package defines the canonical wire-level contract that governs communication between the Magnitude SDK and the ACN daemon. It specifies the RPC surface, serialization schemas, and service boundaries required for type-safe inter-process communication, effectively serving as the trusted interface specification that both sides of the system implement.

### Should client applications import acn-protocol directly?

No. According to the design documentation in [`AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/AGENTS.md) at lines 12-18, client applications must not import from `@magnitudedev/acn-protocol` directly. Instead, they should consume functionality through `@magnitudedev/sdk` or `@magnitudedev/client-common`, which provide stable public APIs while shielding client code from protocol-level changes.

### How does acn-protocol ensure type safety across process boundaries?

The package uses Effect Schemas defined in `packages/acn-protocol/src/schemas/*` to validate and serialize all data crossing the JSON wire boundary. Combined with the AcnRpc adapter in [`packages/acn-protocol/src/boundary/rpc.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn-protocol/src/boundary/rpc.ts), these schemas guarantee that messages conform to expected shapes at both transmission and receipt, catching type mismatches before they cause runtime failures.

### Which services are exposed through the acn-protocol package?

The package exports typed boundaries for core ACN services including **Sessions**, **Projects**, **Models**, and **Display**, all re-exported from [`packages/acn-protocol/src/boundary/index.ts`](https://github.com/magnitudedev/magnitude/blob/main/packages/acn-protocol/src/boundary/index.ts). Each service façade defines the exact method signatures and payload structures that the SDK can invoke and that the daemon must implement.