# How the Runtime-Kernel Manages Admission Control and Client Capabilities in Apache Maka

> Apache Maka's runtime kernel orchestrates session admission via execution claims and acts as a capability broker, controlling client access to host services and external resources.

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

---

**The runtime-kernel serves as the central orchestrator in Apache Maka, governing session admission through execution claims while acting as a capability broker that selectively exposes host services to control what external resources clients can access.**

The runtime-kernel is the core security and scheduling component of the Apache Maka framework. It determines which sessions may execute code at any given moment and manages the boundary between host-provided capabilities and running agents. According to the apache/maka source code, the kernel implements a strict single-ownership model that prevents race conditions while offering fine-grained control over tool access and messaging authority.

## Admission Control Architecture

The admission control system ensures that only one execution context runs within a session at a time, serializing access through explicit claims and mutations.

### Execution Claims via claimExecution

Before any turn or continuation can execute, a client must obtain a `RuntimeExecutionClaim` through the `claimExecution` method (lines 30‑69 in [`packages/runtime/src/runtime-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-kernel.ts)). This claim serves two critical functions: it prevents new runs from being admitted to stopped sessions, and it provides a cancellation signal (`stopSignal`) that can interrupt execution.

The claim mechanism guarantees that the kernel maintains awareness of active executions. When `claimExecution` is invoked, the kernel validates session state and returns a claim object that must be held for the duration of the run. This creates ahappens-before relationship between session state changes and code execution.

### Session-Wide Mutation Serialization

All mutations affecting session state flow through two specialized methods that enforce admission barriers:

- **`runSessionAdmissionMutation`** (lines 71‑78): Handles mutations that modify session admission state
- **`runSessionQuiescentMutation`** (lines 79‑88): Ensures no execution claims exist before proceeding

The `runSessionQuiescentMutation` method specifically checks for active execution claims before allowing mutations like pausing or snapshotting sessions. If any claim exists, the kernel throws `SessionQuiescentMutationBusyError` (lines 84‑86), preventing state corruption from concurrent access.

### Continuation Admission Checks

Resuming saved continuations requires additional admission verification. The kernel checks `hasActiveRuns` to ensure no other executions are active (lines 61‑64), then delegates boundary validation to `continuationAuthority.claimContinuation` (lines 94‑100). This two-phase admission prevents duplicate continuations from running simultaneously while maintaining the single-ownership invariant across the session lifecycle.

## Client Capability Management

Beyond admission control, the runtime-kernel functions as a **capability gateway** that selectively injects host services into agent execution contexts.

### Capability Gateway Fields

The kernel exposes three primary capability fields through its `RuntimeKernelDeps` interface:

- **`toolBoundaryProtocol`** (lines 84‑85): Provides access to sandboxed tool execution APIs
- **`messageAuthority`** (lines 98‑99): Enables host mediation of message queues in hosted composition mode
- **`interactionAuthority`** (lines 100‑101): Allows the host to manage interactive UI requests on behalf of agents

When these fields are present in the kernel's dependencies, the corresponding capabilities become available to running agents. Missing fields indicate disabled capabilities for that session.

### Injecting Capabilities into AgentRun

When `startTurn` initiates a new execution (line 71), the kernel conditionally injects capability objects into the `AgentRun` constructor based on available dependencies:

```typescript
run = new AgentRun({
  // …
  ...(this.deps.toolBoundaryProtocol
    ? { toolBoundaryProtocol: this.deps.toolBoundaryProtocol }
    : {}),
  // …
});

```

This excerpt from lines 81‑84 demonstrates how the kernel acts as a policy-enforcer, only exposing capabilities that were explicitly provided during kernel initialization. The agent receives a filtered view of host resources, preventing unauthorized access to system-level functionality.

## Practical Implementation Examples

### Starting a Turn (Admission Flow)

```typescript
// Acquire a claim for session "s1"
const claim = runtimeKernel.claimExecution('s1');

// Start a new user turn; the kernel enforces admission
for await (const ev of runtimeKernel.startTurn('s1', {
  turnId: runtimeKernel.deps.newId(),
  text: 'Explain the weather tomorrow',
  parentRunId: undefined,
})) {
  console.log('Session event:', ev);
}

// Claim is automatically released when the turn finishes

```

This pattern creates a cancellable claim through `claimExecution`, then passes control to `startTurn`, which internally calls `enterExecutionClaim` and validates the admission barrier before attaching the claim to the `AgentRun`.

### Running a Quiescent Session Mutation

```typescript
await runtimeKernel.runSessionQuiescentMutation(['s1'], async () => {
  // No active execution claims allowed – the kernel guarantees exclusivity
  const header = await runtimeKernel.deps.store.readHeader('s1');
  await runtimeKernel.deps.store.updateHeader('s1', { status: 'paused' });
});

```

The kernel guarantees that no execution claims exist for session `s1` before executing the mutation callback. Attempting to run this while a turn is active triggers `SessionQuiescentMutationBusyError`.

### Accessing Host-Provided Capabilities

```typescript
// Inside an AgentRun's tool handler
if (runtimeKernel.deps.toolBoundaryProtocol) {
  const result = await runtimeKernel.deps.toolBoundaryProtocol.invokeTool({
    toolName: 'search',
    args: { query: 'latest news' },
  });
  // Use `result` in the agent's response
}

```

This example shows how agents interact with the kernel's capability layer. The `toolBoundaryProtocol` is only available if the kernel was initialized with this capability, creating a secure boundary between agent code and host system calls.

## Summary

- **The runtime-kernel** enforces single-ownership admission control through the `claimExecution` mechanism in [`packages/runtime/src/runtime-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-kernel.ts) (lines 30‑69).
- **Session mutations** are serialized through `runSessionAdmissionMutation` and `runSessionQuiescentMutation`, with the latter throwing `SessionQuiescentMutationBusyError` when sessions are busy (lines 84‑86).
- **Continuation admission** requires verification through `continuationAuthority.claimContinuation` to prevent overlapping executions (lines 94‑100).
- **Capability management** operates as a broker pattern where `toolBoundaryProtocol`, `messageAuthority`, and `interactionAuthority` are conditionally injected into `AgentRun` instances based on kernel configuration.
- **Security boundaries** are maintained by checking capability field existence before injection during the `startTurn` initialization sequence.

## Frequently Asked Questions

### What happens if code tries to mutate a session while it's actively running?

The runtime-kernel prevents concurrent mutations by throwing `SessionQuiescentMutationBusyError` when `runSessionQuiescentMutation` detects active execution claims (lines 84‑86 in [`runtime-kernel.ts`](https://github.com/apache/maka/blob/main/runtime-kernel.ts)). This ensures session state remains consistent by requiring exclusive access before allowing modifications like pausing or updating session metadata.

### How does the runtime-kernel prevent race conditions during admission?

The kernel implements a **claim-based admission protocol** where `claimExecution` (lines 30‑69) establishes a happens-before relationship between session state and code execution. By checking `hasActiveRuns` and utilizing `continuationAuthority.claimContinuation` (lines 61‑64, 94‑100), the kernel maintains single-ownership invariants that prevent overlapping runs and duplicate admissions.

### Which client capabilities can the runtime-kernel expose to agents?

The kernel can expose three primary capabilities through its dependency interface: `toolBoundaryProtocol` for sandboxed tool execution (lines 84‑85), `messageAuthority` for host-mediated message queues (lines 98‑99), and `interactionAuthority` for managing interactive prompts (lines 100‑101). These are conditionally injected into `AgentRun` instances only when present in the kernel's initialization configuration.

### Where is the core admission logic located in the Apache Maka repository?

The admission control and capability management logic resides in [`packages/runtime/src/runtime-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-kernel.ts), specifically within the `claimExecution` method (lines 30‑69), the mutation methods (lines 71‑88), and the capability injection logic surrounding `startTurn` (line 71). Supporting tests verify these behaviors in [`packages/runtime/src/runtime-kernel.test.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-kernel.test.ts).