Complete Guide to Contracts Defined in the @maka/core Package

The @maka/core package defines pure TypeScript contracts—including the Event model, Message payload structures, Command model, Tool catalog definitions, Workspace version authority types, and Permission plumbing—that unify communication across Apache Maka's runtime, UI, CLI, and host boundaries.

The @maka/core package serves as the foundational type layer for the Apache Maka ecosystem, supplying pure type contracts that ensure type safety across the runtime, UI, host, and CLI components. These contracts act as the single source of truth for all cross-boundary communication in the Maka architecture. Understanding the contracts defined in the @maka/core package is essential for developers building extensions, hosts, or clients that interact with the Maka system.

Core Contract Categories

Event Model and Session Events

Located in packages/core/src/events.ts, the Event model provides the unified stream structure for all backend-to-UI and UI-to-backend communication. The foundational BaseEvent interface serves as the root for all event types, while the SessionEvent union type encompasses concrete implementations such as TextDeltaEvent, ToolStartEvent, and ToolResultEvent. The ToolActivityKind enumeration categorizes tool interactions, and ToolOutputStream defines how tool outputs flow through the system. This event-first design ensures exhaustive type handling while allowing future extensions without breaking existing consumers.

Message Payload Contracts

Also defined in packages/core/src/events.ts, the Message payload contracts standardize how user and assistant content is structured across the system. The MessageContent interface represents the core message shape, supporting text, attachments, and inline references. Supporting types include AttachmentRef for file references, QuoteRef for quoted content, InlineReference for contextual pointers, and StorageRef for session file locations. Helper functions such as normalizeMessageContent, aggregateMessageContents, and messageContentDigest ensure payload consistency regardless of origin.

Command Model

The Command model in packages/core/src/events.ts (SessionCommand section) defines the structures for UI-initiated actions sent to sessions. The SessionCommand union type covers operations such as sending text (send), stopping generation (stop), and responding to permission or plan requests. The AttachmentIngestItem interface handles file ingestion metadata. Because commands travel through the same typed channels as events, the UI and runtime share a single source of truth for request/response shapes.

Tool Catalog Definitions

Found in packages/core/src/tool-catalog.ts, the Tool catalog contracts provide immutable descriptions of available tools and host surfaces. CatalogToolDef describes individual tool capabilities, while CatalogSurfaceDef defines host integration points. The constants MAKA_CATALOG_TOOLS and MAKA_CATALOG_SURFACES are deeply frozen objects that serve as the runtime registry. Helper functions like catalogToolByName, catalogSurfaceById, catalogToolNameSet, and unknownBoundToolNames expose read-only views of the catalog, ensuring host products know what can be invoked without risk of mutation.

Workspace Version Authority

Located in packages/core/src/workspace-version-authority.ts, these contracts govern workspace snapshots, epochs, and versioning semantics. Key types include WorkspaceEpochDescriptorV1 for epoch metadata, WorkspaceBaselineDescriptorV1 for baseline states, WorkspaceAuthorityIdentity for authentication contexts, and WorkspaceAuthorityIssue for validation errors. These types ensure consistent versioning semantics across distributed Maka instances and persistent storage layers.

Permission and Runtime Plumbing

The Permission plumbing types, re-exported via packages/core/src/events.ts and defined in packages/core/src/permission.ts, handle security boundaries between UI and runtime. Core contracts include PermissionRequest, PermissionResponse, AdditionalPermissionRequest, and SandboxEscalationRequest. The PermissionMode enumeration defines available security contexts. Additional runtime contracts in packages/core/src/runtime-policy.ts, session-name.ts, health.ts, and diagnostic-log.ts provide RuntimePolicy, SessionName, SessionEventHealth, and DiagnosticLog types for session lifecycle management.

Architectural Principles of @maka/core Contracts

The @maka/core package adheres to several architectural constraints that ensure reliability across the Maka ecosystem.

Pure-Type Boundary – The package contains no implementation code, only TypeScript type declarations and immutable constants. All other packages import these types to maintain type compatibility while implementing platform-specific logic.

Event-First Design – Every interaction is expressed as a SessionEvent. The UI subscribes to the event stream while the runtime pushes events, with the union type guaranteeing exhaustive handling in switch statements and pattern matching.

Immutable Catalog – MAKA_CATALOG_TOOLS and MAKA_CATALOG_SURFACES are deeply frozen objects. Host products read from these constants to discovery available capabilities, while helper functions provide safe, read-only access patterns.

Working with Core Contracts (Code Examples)

Here are practical implementations of the contracts defined in the @maka/core package.

Building a Typed Message Payload

import { MessageContent, AttachmentRef, StorageRef } from '@maka/core';

const imgRef: StorageRef = { 
  kind: 'session_file', 
  sessionId: 's1', 
  relativePath: 'tmp/img.png' 
};

const attachment: AttachmentRef = {
  kind: 'image',
  name: 'screenshot.png',
  mimeType: 'image/png',
  bytes: 12345,
  ref: imgRef,
};

const msg: MessageContent = {
  text: 'Here is the screenshot',
  attachments: [attachment],
};

Looking Up Tool Definitions from the Catalog

import { catalogToolByName, CatalogToolDef } from '@maka/core';

const tool: CatalogToolDef | undefined = catalogToolByName('WebSearch');
if (tool) {
  console.log(`Tool "${tool.name}" is available with effects:`, tool.effects);
}

Sending a Session Command from the UI

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

const sendCommand: SessionCommand = {
  type: 'send',
  turnId: 't-123',
  text: 'Explain the latest log file',
  attachmentItems: [{ name: 'log.txt', base64: 'SGVsbG8=' }],
};

Emitting a Tool-Start Event from the Runtime

import { ToolStartEvent, ToolActivityKind } from '@maka/core';

const toolStart: ToolStartEvent = {
  id: 'e-456',
  turnId: 't-123',
  ts: Date.now(),
  type: 'tool_start',
  toolUseId: 'u-789',
  toolName: 'WebSearch',
  activityKind: 'websearch' as ToolActivityKind,
  args: { query: 'Maka project status' },
};

Key Source Files

Understanding the file structure helps navigate the contracts defined in the @maka/core package:

• packages/core/src/events.ts – Contains BaseEvent, the SessionEvent union, concrete event interfaces (TextDeltaEvent, ToolStartEvent, ToolResultEvent), MessageContent family, and SessionCommand types.
• packages/core/src/tool-catalog.ts – Defines CatalogToolDef, CatalogSurfaceDef, and the immutable catalog constants MAKA_CATALOG_TOOLS and MAKA_CATALOG_SURFACES with helper functions.
• packages/core/src/workspace-version-authority.ts – Houses workspace versioning contracts including WorkspaceEpochDescriptorV1 and WorkspaceBaselineDescriptorV1.
• packages/core/src/runtime-policy.ts, session-name.ts, health.ts, diagnostic-log.ts – Provide auxiliary contracts for RuntimePolicy, SessionName, SessionEventHealth, and DiagnosticLog.
• packages/core/package.json – Configures the export map that makes these modules reachable via /dist/... paths for consumers.

Summary

The contracts defined in the @maka/core package form the type-level API of Apache Maka, ensuring cross-component compatibility without implementation coupling:

• Event Model – Unified SessionEvent union and BaseEvent interface in events.ts for all runtime-UI communication.
• Message Payloads – MessageContent, AttachmentRef, and storage references that normalize user content.
• Command Model – SessionCommand types that standardize UI-to-runtime actions.
• Tool Catalog – Immutable CatalogToolDef and MAKA_CATALOG_TOOLS registry with safe lookup helpers.
• Workspace Authority – Versioning contracts like WorkspaceEpochDescriptorV1 for snapshot consistency.
• Pure Type Safety – Zero implementation code ensures consumers can rely on these contracts as a stable binary interface.

Frequently Asked Questions

What is the difference between BaseEvent and SessionEvent in @maka/core?

BaseEvent is the foundational interface containing common fields like id, turnId, ts, and type that all events share. SessionEvent is a discriminated union type in packages/core/src/events.ts that includes all concrete event implementations such as TextDeltaEvent, ToolStartEvent, and ToolResultEvent, allowing for exhaustive type checking in event handlers.

How does the Tool catalog ensure immutability in Apache Maka?

The MAKA_CATALOG_TOOLS and MAKA_CATALOG_SURFACES constants are deeply frozen objects defined in packages/core/src/tool-catalog.ts. Host products cannot mutate these catalogs directly; instead, they use read-only helper functions like catalogToolByName and catalogToolNameSet to query available tools, ensuring runtime stability and predictable tool availability.

Can I extend the contracts defined in @maka/core for custom Maka plugins?

While @maka/core defines the base contracts, you can extend them through TypeScript declaration merging or by implementing custom event handlers that consume the SessionEvent union. However, the core contracts themselves in packages/core/src/events.ts should not be modified directly, as they serve as the stable binary interface between the UI, runtime, and host components.

Where are permission handling types defined in the @maka/core package?

Permission types such as PermissionRequest, PermissionResponse, and SandboxEscalationRequest are defined in packages/core/src/permission.ts and re-exported through packages/core/src/events.ts. These contracts govern the security boundary between untrusted UI code and the privileged runtime host, ensuring structured permission escalation flows.

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