Apache Maka APIs: Complete Reference for the Modular Runtime

Apache Maka exposes eight distinct public APIs—including a Runtime Host bridge, SessionManager façade, Model Provider interfaces, Tool contracts, SQLite Storage layer, CLI commands, React UI components, and Peer-Mesh networking—all explicitly exported through TypeScript declarations and package.json exports fields.

Apache Maka is built as a modular, multi-package TypeScript monorepo where every public surface is strictly defined. Each package declares its consumer-facing entry points in the exports field of its package.json, ensuring type-safe access to runtime operations, model providers, and client interfaces.

Core Runtime APIs

The foundation of Apache Maka consists of two primary APIs that manage the relationship between the host environment and session execution.

Runtime Host API

The Runtime Host API (@maka/runtime-host) provides a sandboxed bridge between the Electron renderer and the underlying Runtime Host. Implemented in packages/runtime-host/src/preload/preload.ts, this API exposes methods via window.maka.* for creating sessions, sending messages, and subscribing to runtime events. It ensures secure isolation between the UI layer and the core runtime while enabling bidirectional communication.

SessionManager API

The SessionManager API (@maka/runtime) serves as the public façade for all runtime operations. Defined in packages/runtime/src/session-manager.ts and re-exported via packages/runtime/src/index.ts, this API creates SessionManager instances that own sessions, queue turns, and stream RuntimeEvent objects. All UI clients—including Desktop, TUI, and CLI—interact with the runtime exclusively through this interface, making it the central entry point for session lifecycle management.

Model and Tool Integration

Apache Maka abstracts third-party LLM providers and tool execution through standardized interfaces that enable pluggable model support and extensible tool calling.

Model Provider APIs

The Model Provider APIs (@maka/mcp) wrap third-party LLM services such as OpenAI, Anthropic, and Google Gemini. Each provider implements the common ModelProvider interface defined in the package, exposing chat, embed, complete, and streaming methods. Provider implementations reside in files like packages/mcp/src/provider-openai.ts and provider-anthropic.ts, offering consistent access to diverse model backends through a unified contract.

Tool APIs

Tool APIs define the contracts for model-invoked functions used during runtime execution. Located in packages/runtime/src/tool-*.ts (e.g., tool-format.ts, tool-output-stream.ts) and augmented by @maka/computer-use, these APIs specify how tools are discovered via the ToolRegistry and invoked through the RuntimeKernel. The Computer-Use package adds a dedicated backend protocol (maka-cu-protocol.ts) for specialized tool execution environments.

Infrastructure and Storage

Persistent state management and distributed networking capabilities are exposed through dedicated infrastructure APIs.

Storage API

The Storage API (@maka/storage) provides a thin wrapper around SQLite databases for persisting runtime state. Implemented in packages/storage/src/sqlite-store.ts, this API manages runtime.sqlite files, connection catalogs, credential vaults, and persisted artifacts. Key methods include open, query, transaction, and migration helpers, offering transactional integrity for workspace data.

Peer-Mesh API

The Peer-Mesh API (@maka/peer-mesh) enables direct-peer networking between multiple Runtime Hosts. Exported from packages/peer-mesh/src/peer-mesh.ts, it provides connect, broadcast, and joinRoom primitives for distributed execution scenarios, allowing multiple Maka instances to coordinate across network boundaries without centralized infrastructure.

Client Interfaces

Apache Maka provides distinct APIs for command-line and graphical interface development, both consuming the same underlying runtime façade.

CLI API

The CLI API (@maka/cli) offers a command-line interface entry point defined in packages/cli/src/cli.ts. Invoked as the maka command (or npm run cli:dev during development), it parses sub-commands including run, graph, export, and import, forwarding all operations to the same SessionManager façade used by graphical clients. This ensures behavioral parity between terminal and desktop interfaces.

UI Component API

The UI Component API (@maka/ui) exposes React components and utility hooks through a barrel export in packages/ui/src/index.ts. Public exports include components like ChatView and hooks such as useChatScroll and useComposerHistory. The API is deliberately scoped to cross-package consumers, with internal components kept private to maintain encapsulation.

Implementation Examples

Using the SessionManager API

import { SessionManager } from '@maka/runtime';

// Create a new session (default workspace)
const manager = await SessionManager.create({
  workspacePath: '/tmp/maka-workspace',
});

// Send a user message and receive a streamed turn
const turn = manager.startTurn({
  role: 'user',
  content: 'Summarize the Apache Maka repository.',
});

for await (const event of turn.events) {
  console.log(event); // RuntimeEvent objects (model output, tool calls, etc.)
}

Source: packages/runtime/src/session-manager.ts

Accessing the Runtime Host Bridge

// In a React component running inside the Electron renderer
window.maka.createSession({ workspace: 'default' })
  .then(session => {
    return session.sendMessage({ role: 'user', content: 'List the public APIs.' });
  })
  .then(events => {
    // `events` is an async iterator of RuntimeEvent objects
    for await (const ev of events) {
      console.log(ev);
    }
  });

Source: packages/runtime-host/src/preload/preload.ts

Invoking a Model Provider Directly

import { OpenAIProvider } from '@maka/mcp';

// Initialise provider with an API key (stored in the local credential vault)
const provider = new OpenAIProvider({ apiKey: 'sk-…' });

const response = await provider.chat({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Explain the purpose of the CLI API.' }],
});

console.log(response.choices[0].message.content);

Source: packages/mcp/src/provider-openai.ts

Storing Artifacts with the Storage API

import { SQLiteStore } from '@maka/storage';

const store = await SQLiteStore.open('/path/to/workspace/runtime.sqlite');

// Insert an artifact
await store.run(`
  INSERT INTO artifacts (id, type, payload)
  VALUES (?, ?, ?)
`, ['artifact-123', 'json', JSON.stringify({ foo: 'bar' })]);

Source: packages/storage/src/sqlite-store.ts

Using UI Components in React

import { ChatView, useComposerHistory } from '@maka/ui';

export function MyChat() {
  const { history, addMessage } = useComposerHistory();

  return (
    <ChatView
      messages={history}
      onSend={msg => addMessage({ role: 'user', content: msg })}
    />
  );
}

Source: packages/ui/src/index.ts

Summary

• Runtime Host API: Exposes window.maka.* bridge in packages/runtime-host/src/preload/preload.ts for Electron renderer communication.
• SessionManager API: Central façade in packages/runtime/src/session-manager.ts for session lifecycle and event streaming.
• Model Provider APIs: Unified interface in @maka/mcp for OpenAI, Anthropic, and Gemini integrations.
• Tool APIs: Registry and kernel execution contracts in packages/runtime/src/tool-*.ts and Computer-Use protocols.
• Storage API: SQLite persistence layer in packages/storage/src/sqlite-store.ts with transactional support.
• CLI API: Command-line interface in packages/cli/src/cli.ts proxying to SessionManager.
• UI Component API: React library in packages/ui/src/index.ts exporting ChatView and interaction hooks.
• Peer-Mesh API: Distributed networking primitives in packages/peer-mesh/src/peer-mesh.ts.

Frequently Asked Questions

How do I access Apache Maka APIs from a desktop application?

Desktop applications access the Runtime Host API through the window.maka object exposed by the Electron preload script in packages/runtime-host/src/preload/preload.ts. This bridge provides methods like createSession and sendMessage that communicate with the underlying SessionManager while maintaining process isolation between the renderer and main threads.

What is the primary entry point for runtime operations?

The SessionManager class, exported from @maka/runtime via packages/runtime/src/session-manager.ts, serves as the sole public façade for runtime operations. All clients—including CLI, TUI, and Desktop—must instantiate a SessionManager using SessionManager.create() to initiate sessions, queue turns, and subscribe to RuntimeEvent streams.

Are Apache Maka APIs type-safe?

Yes. All Apache Maka APIs ship with full TypeScript declarations. The repository uses package.json exports fields to explicitly define public entry points, preventing accidental imports of internal modules. This ensures compile-time verification of method signatures, event types, and provider interfaces across the monorepo.

How does Apache Maka handle persistent storage?

The Storage API (@maka/storage) wraps SQLite databases through the SQLiteStore class in packages/storage/src/sqlite-store.ts. It provides methods for open, query, and transaction operations, storing data in runtime.sqlite files alongside workspace directories. This API manages everything from runtime state to encrypted credential vaults and serialized artifacts.

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