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

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 (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 and 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 (line 12).

Provider Client Surface for AI Inference

The ProviderClient API, defined in packages/sdk/src/provider-client.ts and exported from 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.

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 (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.

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: 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: Implements model catalog retrieval, inference calls, and utility service endpoints.
• 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: Manages local ACN daemon lifecycle, including binary path resolution and graceful shutdown supervision.
• packages/sdk/src/tracing.ts: Provides tracing utilities that integrate with the Motel OpenTelemetry collector.
• 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:

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 (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 (lines 55-71).

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

Re-exporting types from 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/.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}