What Is the packages/core Directory in Apache Maka? Foundational Types Explained

The packages/core directory in Apache Maka contains the foundational, pure-type-only building blocks that define session semantics, capability modeling, and event contracts for the entire platform.

The packages/core directory serves as the type-safe foundation of the Apache Maka repository, providing the canonical data models and serialization-aware contracts that all other packages depend on. Located within the monorepo's packages/ folder, this directory defines how sessions, capabilities, and runtime events are represented, validated, and exchanged across the entire codebase. Every higher-level package—from UI components to agent implementations—imports from @maka/core to maintain consistency with this architectural single source of truth.

Core Responsibilities of packages/core

The packages/core directory delivers four critical responsibilities that power the Maka platform's data integrity and cross-package communication.

Session and Turn Management

At the heart of the package lies the session model defined in src/session.ts. This file establishes immutable session headers, status enumerations, and helper functions that govern turn-record derivation, sub-agent lineage tracking, and revision handling. The session schema ensures that every interaction within Maka adheres to a strict, versioned structure that supports complex conversation flows and branching agent hierarchies.

Capability and Permission Modeling

The src/capabilities.ts file defines the capability readiness system that determines whether platform features can activate based on OS permissions, configuration states, and runtime probes. This module exports the deriveCapabilityReadiness algorithm, which aggregates inputs from feature flags, settings, and system permissions to compute a definitive readiness state. The capability snapshot types enable the UI layer to render accurate permission states while maintaining type safety across the capability lifecycle.

Event and Message Contracts

Data integrity across persistence layers relies on the strict decoders implemented in src/events.ts. These decoders validate every stored message type—including user inputs, assistant responses, tool calls, and permission decisions—ensuring that data retrieved from storage or network layers conforms to expected schemas. The decodeStoredMessage function provides runtime validation that prevents corrupted or malformed data from propagating through the system.

Public API Stability

The package.json in packages/core declares an exports map that exposes a stable public API while keeping implementation details private. The description field identifies the package as "Pure types for Maka — events, session, permission, connections," accurately summarizing its role. Consumers access specific submodules via paths like @maka/core/session or @maka/core/capabilities, enabling tree-shaking and explicit dependency management.

Key Files in packages/core

Understanding the file structure demonstrates how the package organizes its type definitions and logic:

• packages/core/package.json — Declares the package metadata and export map that defines the public surface area for @maka/core imports.
• packages/core/src/session.ts — Contains the central SessionHeader interface, status enums, and utility functions that drive the entire session persistence model.
• packages/core/src/capabilities.ts — Houses the CapabilitySnapshot types and the deriveCapabilityReadiness function that powers the capability health UI.
• packages/core/src/events.ts — Implements the decodeStoredMessage decoder and message type definitions that guarantee data integrity across storage layers.
• packages/core/src/__tests__/ — Contains comprehensive test suites including session-event.test.ts and capabilities.test.ts that validate type correctness and algorithm behavior.

Practical Usage Examples for @maka/core

The following examples demonstrate how to leverage the pure types and utilities exported from the packages/core directory.

Creating a Session Header

Import the SessionHeader type to ensure your session initialization adheres to the canonical schema:

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

const header: SessionHeader = {
  id: 'session-123',
  workspaceRoot: '/Users/alice/project',
  cwd: '/Users/alice/project',
  createdAt: Date.now(),
  name: 'Demo Session',
  titleIsManual: false,
  isFlagged: false,
  labels: [],
  isArchived: false,
  status: 'active',
  hasUnread: false,
  backend: 'ai-sdk',
  llmConnectionSlug: 'openai-gpt-4',
  connectionLocked: false,
  model: 'gpt-4',
  permissionMode: 'allow',
};

Deriving Capability Readiness

Use the deriveCapabilityReadiness function to calculate whether a capability can be enabled based on system state:

import {
  deriveCapabilityReadiness,
  type CapabilitySnapshot,
  type DeriveCapabilityReadinessInput,
} from '@maka/core';

const input: DeriveCapabilityReadinessInput = {
  feature: { state: 'enabled', source: 'settings' },
  configuration: { state: 'present', source: 'runtime' },
  osPermissions: [
    { id: 'accessibility', required: true, status: 'granted' },
    { id: 'screen_recording', required: true, status: 'granted' },
  ],
  runtimeProbe: { state: 'healthy', source: 'bot_registry' },
};

const readiness = deriveCapabilityReadiness(input); // → 'enabled'

Decoding Stored Messages Safely

Validate and type unknown data using the strict decoder pattern:

import { decodeStoredMessage } from '@maka/core';
import type { StoredMessage } from '@maka/core';

const raw = JSON.parse(`{
  "type":"assistant","id":"msg-1","turnId":"turn-1","ts":1690000000000,
  "text":"Hello!", "modelId":"gpt-4"
}`);

const message: StoredMessage = decodeStoredMessage(raw);
// `message` is now strongly typed as AssistantMessage.

Summary

• The packages/core directory provides pure TypeScript types with zero runtime dependencies, ensuring lightweight imports across the monorepo.
• Session management relies on src/session.ts for immutable headers and turn-semantics that support complex agent hierarchies.
• Capability modeling uses the deriveCapabilityReadiness algorithm in src/capabilities.ts to aggregate OS permissions, feature flags, and runtime health into deterministic readiness states.
• Data integrity is enforced through strict decoders like decodeStoredMessage in src/events.ts, preventing malformed data from corrupting application state.
• The exports map in package.json exposes a stable public API via submodule paths, allowing precise imports such as @maka/core/session or @maka/core/capabilities.

Frequently Asked Questions

What types are exported from @maka/core?

The package exports pure TypeScript interfaces and types including SessionHeader, CapabilitySnapshot, StoredMessage, and various enums for session status and permission states. According to the package.json description, the focus remains on events, session management, permissions, and connections.

How does deriveCapabilityReadiness determine if a capability is ready?

The deriveCapabilityReadiness function accepts a DeriveCapabilityReadinessInput object containing feature flags, configuration presence, OS permission arrays, and runtime probe states. As implemented in src/capabilities.ts, the algorithm evaluates these inputs hierarchically to return a readiness state such as 'enabled', 'disabled', or 'missing_permissions'.

Is packages/core available as a standalone dependency?

While packages/core exists as a discrete package within the Apache Maka monorepo, it is primarily designed for internal consumption by other Maka packages. The package.json declares the exports field that enables precise submodule imports, suggesting it could theoretically be published independently, though it serves as the shared contract layer for the broader application.

How does packages/core ensure data integrity across storage layers?

Data integrity is maintained through strict decoder functions like decodeStoredMessage defined in src/events.ts. These decoders validate JSON payloads against expected schemas at runtime, throwing errors when fields are missing or types mismatch, thereby guaranteeing that only valid data structures propagate through the persistence and network layers.

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