What Is the packages/core Directory in Apache Maka? Architecture and Purpose

The packages/core directory serves as Apache Maka's foundational "pure-type" layer, defining canonical data models, enums, and serialization contracts that provide a stable, versioned API consumed by all other packages in the monorepo.

The packages/core directory establishes the architectural bedrock of the Apache Maka project. Located within the monorepo structure, this package contains the immutable domain types and lightweight utilities that describe system entities—such as sessions, capabilities, and work items—without coupling to platform-specific implementation details. By maintaining strict separation between type definitions and execution logic, @maka/core enables consistent data contracts across both the main Node.js process and browser renderer contexts.

Core Responsibilities and Architecture

The primary function of packages/core is to declare what the system knows and how that knowledge is represented, while leaving how it is executed to higher-level packages like runtime, cli, and ui.

Domain Type Definitions

The package establishes a single source of truth for runtime entities through TypeScript type declarations. Key definitions include SessionStatus, CapabilityId, and ConnectionReadinessState, which are declared in files such as packages/core/src/session.ts and packages/core/src/capabilities.ts.

This centralization prevents type drift between the main process and UI layers. When the system needs to check if a session is active, it references the same SessionStatus enum regardless of whether the code executes in the Node backend or the browser frontend.

Serialization Contracts

packages/core houses the encoding and decoding logic required for durable storage and cross-process communication. Functions like decodeMessageContent and decodeCanonicalToolResultContent in packages/core/src/events.ts provide standardized serialization contracts.

These utilities allow the runtime to remain agnostic of the transport layer while ensuring that events and tool results maintain consistent shape across process boundaries. The record schemas defined here enable reliable data persistence without importing platform-specific storage APIs.

Pure-Type Guarantees

A strict architectural constraint governs packages/core: the code must remain pure TypeScript with no direct dependencies on Electron, Node.js, or browser APIs. This purity enables the same definitions to be safely reused in both the main process and renderer process without side effects or environment-specific branching logic.

By avoiding platform dependencies, the package guarantees that importing a type definition never inadvertently pulls in heavy runtime dependencies or triggers unexpected I/O operations.

Public API and Module Exports

The package.json in packages/core defines a clean public API through the exports field. This configuration maps logical module paths to their compiled counterparts under dist/, enabling intuitive imports like:

import { SessionStatus, CapabilityId } from '@maka/core';

For example, the export map routes ./session to ./dist/session.js, allowing downstream packages to rely on stable import paths while the core team maintains flexibility with internal file organization. This contract ensures that changes to internal directory structures do not break consuming packages across the monorepo.

Key Source Files in packages/core

The following files collectively form the immutable contract powering Maka's distributed architecture:

• src/session.ts – Defines session lifecycles, status enums, and the WORKHUB_COORDINATION_SESSION_ID constant used to identify the special WorkHub coordination session.
• src/capabilities.ts – Enumerates available capabilities through CapabilityId and tracks permission states via CapabilityReadinessState.
• src/work-board.ts – Declares the durable WorkBoard schema and versioning constants like WORK_BOARD_ITEM_SCHEMA_VERSION for user-owned work items.
• src/connections.ts and src/connection-readiness.ts – Describe connection objects and their readiness states.
• src/events.ts – Provides event and tool-result type definitions used throughout the platform, including serialization helpers.
• package.json – Exposes the public API via the exports map and documents the package's purpose as the shared type foundation.

Usage Examples: Consuming @maka/core

Other packages throughout the Maka ecosystem import from @maka/core to maintain type consistency. Below are typical implementation patterns derived from the source code.

Importing Session Types

import { SessionStatus, WORKHUB_COORDINATION_SESSION_ID } from '@maka/core';

// Check a session's status
function isActive(status: SessionStatus): boolean {
  return status === 'active';
}

// Detect the special WorkHub coordination session
function isWorkHub(sessionId: string): boolean {
  return sessionId === WORKHUB_COORDINATION_SESSION_ID;
}

(Source: [packages/core/src/session.ts](https://github.com/apache/maka/blob/main/packages/core/src/session.ts))

Using Capability Enums

import { CapabilityId, CapabilityReadinessState } from '@maka/core';

function canRunCapability(cap: CapabilityId, readiness: CapabilityReadinessState) {
  return readiness === 'enabled' && cap === 'computer_use';
}

(Source: [packages/core/src/capabilities.ts](https://github.com/apache/maka/blob/main/packages/core/src/capabilities.ts))

Defining Work-Board Items

import { defineObjectShape, hasExactShape, WORK_BOARD_ITEM_SCHEMA_VERSION } from '@maka/core';

export const myWorkItem = defineObjectShape({
  version: WORK_BOARD_ITEM_SCHEMA_VERSION,
  title: 'Write knowledge-base article',
  createdAt: Date.now(),
});

(Source: [packages/core/src/work-board.ts](https://github.com/apache/maka/blob/main/packages/core/src/work-board.ts))

Checking Connection Readiness

import { ConnectionReadinessState } from '@maka/core';

function isReady(state: ConnectionReadinessState): boolean {
  return state === 'ready';
}

(Source: [packages/core/src/connection-readiness.ts](https://github.com/apache/maka/blob/main/packages/core/src/connection-readiness.ts))

Summary

The packages/core directory functions as the "brain" of Apache Maka, establishing the foundational contracts that enable the system's modular architecture:

• Immutable Type Contracts: Provides the single source of truth for domain entities like sessions, capabilities, and work items across all processes.
• Platform Agnostic Design: Maintains pure TypeScript implementations without Electron, Node.js, or browser API dependencies, ensuring safe reuse in any execution context.
• Serialization Foundation: Houses encoding/decoding logic for cross-process communication and durable storage.
• Stable Public API: Exports versioned types through a carefully curated package.json exports map, allowing downstream packages to import @maka/core with confidence.

Frequently Asked Questions

What types of definitions are stored in packages/core?

The directory contains "pure-type" definitions including TypeScript interfaces for SessionStatus, CapabilityId, and WorkBoard schemas, along with lightweight utility functions for serialization like decodeMessageContent. These definitions describe runtime entities without implementing platform-specific behavior.

Why does packages/core avoid platform-specific APIs?

By prohibiting direct usage of Electron, Node.js, or browser APIs, packages/core ensures that type definitions can be safely imported into both the main Node.js process and the browser renderer process. This architectural constraint prevents side effects and keeps the package lightweight, avoiding heavy runtime dependencies that would bloat the renderer bundle.

How do runtime packages consume types from core?

Runtime packages like runtime and ui import types using the @maka/core package name, which maps to the compiled output of packages/core. The exports field in packages/core/package.json routes specific paths (e.g., @maka/core/session) to their corresponding dist/ files, providing a stable import interface regardless of internal file restructuring.

What is the relationship between packages/core and the runtime layer?

packages/core declares what data structures exist and how they are represented, while packages/runtime and other implementation packages handle how that data is processed and executed. The core package provides the immutable contracts, while runtime layers provide the platform-specific logic that operates on those contracts.

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