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

> Discover the TypeScript contracts in @maka/core like Event, Message, and Command. Unify communication across Maka's runtime, UI, CLI, and host boundaries.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: api-reference
- Published: 2026-08-26

---

**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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/core/src/events.ts) and defined in [`packages/core/src/permission.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-policy.ts), [`session-name.ts`](https://github.com/apache/maka/blob/main/session-name.ts), [`health.ts`](https://github.com/apache/maka/blob/main/health.ts), and [`diagnostic-log.ts`](https://github.com/apache/maka/blob/main/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

```typescript
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

```typescript
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

```typescript
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

```typescript
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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/core/src/workspace-version-authority.ts)** – Houses workspace versioning contracts including `WorkspaceEpochDescriptorV1` and `WorkspaceBaselineDescriptorV1`.
- **[`packages/core/src/runtime-policy.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-policy.ts)**, **[`session-name.ts`](https://github.com/apache/maka/blob/main/session-name.ts)**, **[`health.ts`](https://github.com/apache/maka/blob/main/health.ts)**, **[`diagnostic-log.ts`](https://github.com/apache/maka/blob/main/diagnostic-log.ts)** – Provide auxiliary contracts for `RuntimePolicy`, `SessionName`, `SessionEventHealth`, and `DiagnosticLog`.
- **[`packages/core/package.json`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/core/src/permission.ts) and re-exported through [`packages/core/src/events.ts`](https://github.com/apache/maka/blob/main/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.