Understanding the Purpose of `packages/core` in Apache Maka

The packages/core module in Apache Maka serves as the pure contract layer that defines immutable data structures, validation logic, and serialization limits for sessions, runtime events, permissions, and sandbox boundaries, establishing a single source of truth for all inter-package communication.

The Apache Maka repository organizes its architecture into distinct packages, with packages/core acting as the foundational backbone that remains free of side-effects and runtime-specific implementations. By isolating these definitions from execution logic, the core package ensures that every component—from the CLI to the runtime host—speaks the same protocol when handling interaction requests, permission prompts, and sandbox expansions.

The Role of packages/core as a Pure Contract Layer

At its essence, packages/core houses pure contracts that describe how data flows through the Maka ecosystem. According to the repository's documentation, this directory contains "Pure contracts for Sessions, Events, Permissions, and Connections"[^README.md:65-66^], making it the stable interface upon which all other packages depend.

Unlike the runtime or runtime-host packages that contain execution logic, the core module focuses exclusively on:

• Immutable data shapes that prevent mutation across package boundaries
• Validation helpers that enforce size limits and structural constraints before data reaches the runtime
• Canonical outcome definitions that standardize how success and failure states are represented
• Serialization contracts that support Maka's high-performance, append-only event log

Other packages such as cli, ui, and runtime import these contracts via the @maka/core namespace, ensuring consistent protocol adherence without coupling to implementation details.

Core Functional Domains

The packages/core directory organizes its contracts into several key domains that govern agent-host interactions.

Session and Interaction Modeling

The central definitions for session management reside in packages/core/src/interaction.ts. This file exports types like InteractionRequest and InteractionAnswer along with their canonical outcomes. These structures model the complete lifecycle of a user-agent exchange, from the initial request projection to the final validation of responses.

Permission Handling

Security-critical permission flows are defined in packages/core/src/permission.ts. This module specifies structures for permission prompts, risk level classifications, reviewer assignments, and audit trail entries. By centralizing these definitions, Maka ensures that permission grants maintain consistent metadata and validation rules across all UI implementations.

Sandbox Boundary Management

Safe expansion of execution privileges is governed by packages/core/src/sandbox-boundary.ts. The contracts here define request and decision types that control read, write, and network access extensions. These immutable boundaries prevent runtime hosts from accidentally over-privileging agents during execution.

Client Capability Grants

The packages/core/src/client-capability-grant.ts file structures how agents request capabilities from their host environment. These grants follow strict validation schemas to ensure that capability negotiations remain transparent and auditable within Maka's event log.

Key Source Files and Architecture

The following table maps the critical files within packages/core to their specific responsibilities:

File Path	Description
packages/core/src/interaction.ts	Central definitions for interaction requests, answers, canonical outcomes, and validation helpers
packages/core/src/permission.ts	Types and utilities for permission prompts, reviewers, and risk-level handling
packages/core/src/sandbox-boundary.ts	Contracts governing sandbox-boundary expansion requests and status tracking
packages/core/src/client-capability-grant.ts	Structures for client-capability grant requests and responses
packages/core/src/record-schema.ts	Helper utilities for defining and validating object shapes used throughout the core contracts
packages/core/src/workhub-session-resolver.ts	Session-resolution logic that ties together the core contracts with higher-level workspace concepts
packages/core/src/usage-stats/pricing.ts	Domain-specific contract demonstrating how the core validation framework supports business logic

These files collectively import no runtime-specific dependencies, maintaining the zero side-effect guarantee that makes packages/core suitable for use in both server and client contexts.

Practical Usage Examples

The following examples demonstrate how other packages consume the packages/core contracts to enforce type safety and validation.

Creating a Permission Interaction Request

To initiate a permission flow, packages import projection functions that validate and freeze user input into safe contract shapes:

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

// Build a permission request payload
const permReq = projectInteractionPermissionRequest({
  requestId: 'req-123',
  toolUseId: 'tool-456',
  prompt: {
    kind: 'tool_permission',
    title: 'Access Files',
    description: 'Allow the agent to read/write files in your workspace.',
    rememberForTurnAllowed: true,
    // …other fields defined by InteractionPermissionPrompt
  },
});

// Encode to a safe runtime event
const encoded = decodeInteractionRequest(permReq);

Here, projectInteractionPermissionRequest projects user-provided data into a validated shape, while decodeInteractionRequest performs final validation and freezing before the request enters the event log.

Validating Interaction Answers

Runtime hosts use core validation helpers to verify that incoming answers match their corresponding requests:

import {
  decodeInteractionAnswer,
  isInteractionAnswerValidForRequest,
} from '@maka/core';

// Suppose we received a permission answer from the UI
const answer = decodeInteractionAnswer({
  kind: 'permission',
  decision: 'allow',
  rememberForTurn: true,
});

// Verify the answer matches the original request
if (isInteractionAnswerValidForRequest(permReq, answer)) {
  // Proceed with the granted permission
}

The isInteractionAnswerValidForRequest function ensures that the answer structure aligns with the original request constraints defined in packages/core/src/interaction.ts.

Defining Sandbox Boundary Requests

Agents requesting expanded sandbox permissions use specialized projectors:

import {
  projectInteractionSandboxBoundaryRequest,
  decodeInteractionRequest,
} from '@maka/core';

const sandboxReq = projectInteractionSandboxBoundaryRequest({
  expansion: { read: true, write: false, network: false },
  justification: 'Need to read config files for setup.',
});

const encoded = decodeInteractionRequest(sandboxReq);

These examples illustrate how packages/core enforces strict shape, size, and safety constraints before any interaction reaches the runtime-host package.

Summary

• packages/core provides pure contracts that define immutable data structures for sessions, events, permissions, and sandbox boundaries in Apache Maka
• Zero side-effect architecture ensures these definitions remain free of runtime dependencies, making them safe for import across cli, ui, runtime, and runtime-host packages
• Centralized validation through functions like decodeInteractionRequest and projectInteractionPermissionRequest prevents invalid data from entering the append-only event log
• Key source files including interaction.ts, permission.ts, and sandbox-boundary.ts establish the protocol that drives Maka's high-performance runtime communication
• Single source of truth design ensures that all packages share identical type definitions and validation logic for agent-host interactions

Frequently Asked Questions

What types are defined in packages/core/src/interaction.ts?

The interaction.ts file defines the fundamental structures for request-response cycles, including InteractionRequest, InteractionAnswer, and their canonical outcomes. It also exports validation helpers such as decodeInteractionAnswer and isInteractionAnswerValidForRequest that runtime hosts use to verify interaction integrity before processing.

How does packages/core ensure type safety across the runtime?

By keeping packages/core free of side-effects and runtime-specific code, the module serves as a stable contract layer imported by all other packages. Functions like projectInteractionPermissionRequest and decodeInteractionRequest enforce immutability and structural validation at the boundaries, ensuring that only well-formed data enters the runtime event log.

Can I import @maka/core in external packages or third-party extensions?

Yes, the packages/core module is designed for consumption by any package requiring Maka protocol compliance. External tools and extensions can import the contract definitions to generate valid interaction requests or parse event logs while maintaining compatibility with the core validation rules defined in files like record-schema.ts.

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

The packages/core module provides the data contracts and validation logic, while packages/runtime and packages/runtime-host contain the execution environment that acts upon these contracts. The runtime imports types and validation functions from @maka/core but never the reverse, maintaining a clean separation between protocol definition and protocol execution.

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