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

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). 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:

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)

// 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

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

// 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 (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). 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, 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.

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