Apache Maka Runtime Policy Configuration and Mutation System Explained

Apache Maka maintains a centralized JSON runtime-policy document that governs all agent permissions, resource budgets, and feature toggles, allowing atomic updates only through an optimistic concurrency (CAS) workflow exposed via runtime.policy.* RPC endpoints.

The runtime policy configuration and mutation system in Apache Maka serves as the central nervous system for agent governance. This JSON-driven architecture, defined in packages/core/src/runtime-policy.ts, determines everything from LLM connection access to shell execution privileges, ensuring strict control over agent capabilities while supporting dynamic, thread-safe updates.

Runtime Policy Document Structure

The policy document, persisted as runtime-policy.json, contains eight primary sections that define operational boundaries. The RuntimePolicy TypeScript interface in packages/core/src/runtime-policy.ts and the codec in packages/storage/src/runtime-policy/codec.ts enforce type safety and validation across these domains:

• connectionCatalog: Declares permitted LLM connections with fields like id, name, model, enabled, and optional budget constraints.
• credentialVault: Secures API keys and OAuth tokens mapped to specific connection IDs.
• shell: Controls subprocess execution through enabled flags and command allowlist arrays.
• memory: Toggles long-term memory and incognito (private) mode via boolean flags.
• webSearch: Enables or disables the built-in web-search tool.
• personalization: Stores UI preferences such as assistantTone.
• budget: Enforces global limits on totalTokens and perTurn consumption.
• policyMetadata: Immutable tracking fields including revision, policyKind ('map' | 'supervisor'), and policyFingerprint.

The Optimistic Concurrency Mutation Workflow

Maka enforces policy changes exclusively through a compare-and-swap (CAS) mechanism to prevent race conditions. The mutation system involves four coordinated stages managed by the HostRuntimePolicyCoordinator class in packages/runtime-host/src/server/runtime-policy-coordinator.ts.

Query Phase

Clients initiate changes by calling runtime.policy.query, which returns the current policy snapshot including the critical revision field acting as a CAS token.

Mutate Phase

The runtime.policy.mutate endpoint accepts an expectedRevision and an array of policy operations. The system supports set, delete, add, and remove operations defined in packages/storage/src/runtime-policy/operations.ts. If the stored revision differs from expectedRevision, the system returns a policy_conflict error, forcing the client to re-query.

Coordinator Persistence

The coordinator performs atomic updates through RuntimePolicyStores (packages/storage/src/runtime-policy-stores.ts). It verifies the CAS token, applies operations graph-ically using the codec, and persists to runtime-policy.json. If persistence fails, it returns persistence_failed and poisons the activation gate.

Activation Gate Enforcement

The RuntimePolicyActivationGate class (packages/runtime-host/src/server/runtime-policy-activation-gate.ts) blocks policy-dependent reads during updates or when the policy state is poisoned, ensuring no agent operation executes against an inconsistent or failed policy state.

Implementing Policy Changes in Code

Developers interact with the policy system through RPC endpoints. Below are practical TypeScript implementations demonstrating common mutations.

Querying Current Policy Status

const current = await desktop.request('runtime.policy.query', {});
console.log('Revision:', current.revision);
console.log('Web search enabled?', current.policy.webSearch.enabled);

Enabling Features and Setting Budgets

const snap = await desktop.request('runtime.policy.query', {});

const ops = [
  { op: 'set', path: '/webSearch/enabled', value: true },
  { op: 'set', path: '/budget/totalTokens', value: 500_000 },
];

const mutated = await desktop.request('runtime.policy.mutate', {
  expectedRevision: snap.revision,
  operations: ops,
});
console.log('New revision:', mutated.revision);

Activating Incognito Mode

const { revision } = await desktop.request('runtime.policy.query', {});
await desktop.request('runtime.policy.mutate', {
  expectedRevision: revision,
  operations: [{ op: 'set', path: '/memory/incognito', value: true }],
});

Adding New LLM Connections

await desktop.request('runtime.policy.mutate', {
  expectedRevision: revision,
  operations: [
    {
      op: 'add',
      path: '/connectionCatalog/connections/-',
      value: {
        id: 'gpt-4',
        name: 'OpenAI GPT-4',
        model: 'gpt-4',
        enabled: true,
        budget: { perTurn: 2000 },
      },
    },
  ],
});

Core Source Files and Architecture

The runtime policy system spans multiple packages with clear separation of concerns:

• [packages/core/src/runtime-policy.ts](https://github.com/apache/maka/blob/main/packages/core/src/runtime-policy.ts): Defines the RuntimePolicy interface and type guards.
• [packages/storage/src/runtime-policy/codec.ts](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy/codec.ts): Handles JSON schema validation and encode/decode logic.
• [packages/storage/src/runtime-policy/document-io.ts](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy/document-io.ts): Manages atomic file I/O and temporary file handling for runtime-policy.json.
• [packages/storage/src/runtime-policy-stores.ts](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy-stores.ts): Provides the RuntimePolicyStores class offering getSnapshot, set, and operation methods.
• [packages/storage/src/runtime-policy/operations.ts](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy/operations.ts): Defines PolicyOperation types including set, add, remove, and delete.
• [packages/runtime-host/src/server/runtime-policy-coordinator.ts](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/runtime-policy-coordinator.ts): Implements the CAS verification and atomic mutation logic.
• [packages/runtime-host/src/server/runtime-policy-activation-gate.ts](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/runtime-policy-activation-gate.ts): Enforces policy-dependent access control and poisoned state management.
• [packages/runtime-host/src/__tests__/runtime-policy-coordinator.test.ts](https://github.com/apache/maka/blob/main/packages/runtime-host/src/__tests__/runtime-policy-coordinator.test.ts): Contains end-to-end tests for conflict handling and persistence failures.

Summary

• Apache Maka uses a single JSON document (runtime-policy.json) to govern all agent permissions, budgets, and feature toggles.
• The policy schema in packages/core/src/runtime-policy.ts defines eight primary sections including connection catalogs, credential vaults, and execution constraints.
• All mutations occur through an optimistic concurrency (CAS) workflow requiring an expectedRevision token to prevent race conditions.
• The HostRuntimePolicyCoordinator applies operations atomically, while RuntimePolicyActivationGate blocks unsafe access during updates or failures.
• Clients interact via runtime.policy.query and runtime.policy.mutate RPC endpoints using JSON Patch-style operations.

Frequently Asked Questions

What happens when two clients try to mutate the policy simultaneously?

When concurrent mutations occur, the first successful update increments the revision token. Subsequent requests bearing the stale expectedRevision receive a policy_conflict error and must re-query the current state before retrying. This ensures linearizable updates without locking.

Can I manually edit the runtime-policy.json file while the agent is running?

Manual editing is strongly discouraged. The runtime maintains in-memory state through RuntimePolicyStores and uses temporary file swapping during writes. Manual changes bypass the CAS mechanism and may trigger the persistence_failed state, causing the RuntimePolicyActivationGate to poison execution until consistency is restored.

How does the activation gate protect against policy violations?

The RuntimePolicyActivationGate intercepts policy-dependent operations—such as tool executions requiring credentials or shell commands—and validates them against the current policy snapshot. If the policy is being updated or has entered a poisoned state due to persistence errors, the gate blocks execution to prevent unauthorized or unsafe actions.

What operation types are supported for policy mutations?

The system supports set, delete, add, and remove operations defined in packages/storage/src/runtime-policy/operations.ts. These JSON Patch-style operations allow granular modifications to specific paths like /webSearch/enabled or /connectionCatalog/connections/- without replacing the entire document.

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