How Apache Maka Handles Long-Running Tool Execution: From Seconds to Hours

Apache Maka decouples tool invocation from the LLM response loop by using a Task Ledger architecture that queues long-running operations, allowing subprocesses to execute for hours while streaming progress updates back to the model.

Apache Maka is an open-source AI runtime designed to safely invoke external tools that may block for seconds, minutes, or even hours without freezing the conversational interface. Understanding how Apache Maka handles long-running tool execution requires examining its declarative task ledger system, host-side execution kernel, and streaming update mechanisms.

The Task Ledger Architecture

The foundation of long-running tool support in Apache Maka is the Task Ledger, a backlog queue that separates the LLM's conversational turn from the actual execution of external processes.

Tool Surface Composition

When a conversation turn begins, packages/runtime-host/src/server/interactive-run-composer.ts assembles a tool surface that lists every callable tool available to the model. This surface includes the Task Ledger tools (task_create, task_update, task_get, task_list) alongside host-specific executors such as run, git, or custom tools. By exposing these ledger operations as first-class tools, the runtime allows the model to programmatically queue work without blocking on completion.

Declarative Task Creation

Long-running operations are initiated through task_create, defined in packages/runtime/src/task-ledger-tools.ts. The tool schema accepts parameters including command, args, timeoutMs, and env, creating an immutable ledger entry that describes the work to be performed. The host kernel picks up this entry asynchronously, executing the subprocess while the LLM remains free to continue the conversation or process other tasks.

Host Execution and Timeout Management

Once a task enters the ledger, the host kernel manages the actual subprocess lifecycle with explicit safety controls.

Subprocess Isolation in the Host Kernel

The packages/runtime-host/src/server/host-kernel.ts file implements the execution engine responsible for running tool subprocesses. Each invocation receives a per-call timeout (timeoutMs) that defaults to conservative values (typically 30 seconds for standard commands) but can be overridden via the tool schema to accommodate multi-hour operations. The kernel also enforces an idle timeout to automatically terminate services that remain inactive for extended periods.

Configurable Execution Boundaries

Developers specify execution limits through the timeoutMs field in the task creation payload. For example, a video encoding job that requires two hours of processing time can set timeoutMs: 2 * 60 * 60 * 1000, ensuring the host kernel allows the subprocess to complete without premature termination.

Streaming Progress and Cancellation

Apache Maka provides real-time visibility into long-running operations through bidirectional ledger updates and robust cancellation support.

Real-Time Progress Updates

While a tool executes, it can emit partial results back to the Task Ledger via task_update. The model queries these incremental results using task_get or task_list, enabling the runtime to surface progress indicators ("still working…", "50% done") to the user without waiting for final completion. This streaming pattern ensures that multi-hour tasks feel responsive and transparent.

Graceful Task Cancellation

If a user aborts the conversation or the turn times out, the runtime propagates cancellation signals to the underlying process. The host kernel stores an abort controller reference for each active task, ensuring that resources are freed promptly when operations are terminated early. This prevents zombie processes and resource leaks during extended executions.

Deep Research and Extended Operations

For especially heavyweight operations such as large-scale web searches or complex code-generation pipelines, Apache Maka routes requests through deep-research tool groups. These specialized groups leverage the same Task Ledger mechanism defined in packages/runtime-host/src/server/interactive-run-composer.ts (deep-research section), guaranteeing that multi-minute or multi-hour research jobs are tracked, resumable, and inspectable throughout their lifecycle.

Implementation Example

The following TypeScript pattern demonstrates how to execute a long-running ffmpeg conversion that safely runs for up to two hours:

// 1️⃣ Create a long-running task
const createResult = await requireTaskLedgerTool<TaskCreateInput>(tools, 'task_create')
{
  command: 'ffmpeg',
  args: ['-i', 'input.mp4', '-c:v', 'libx264', 'output.mp4'],
  timeoutMs: 2 * 60 * 60 * 1000, // 2 hours
}

// 2️⃣ Periodically poll for progress
const status = await requireTaskLedgerTool<TaskGetInput>(tools, 'task_get')
{
  taskId: createResult.tasks[0].id,
}

// 3️⃣ The host updates the ledger when the subprocess prints progress.
//    The model surfaces these updates to the user as "still processing…".

The schema for task_create in packages/runtime/src/task-ledger-tools.ts automatically validates payloads before execution begins, ensuring that timeoutMs and other parameters meet contract requirements.

Summary

• Task Ledger Decoupling: task_create in packages/runtime/src/task-ledger-tools.ts queues work asynchronously, separating LLM response generation from tool execution.
• Host-Side Execution: packages/runtime-host/src/server/host-kernel.ts manages subprocess lifecycles with configurable timeoutMs and idle timeouts.
• Streaming Updates: task_update and task_get enable real-time progress reporting for operations lasting minutes or hours.
• Safe Cancellation: Abort controllers ensure resources are freed when users terminate long-running jobs.
• Deep Research Support: Extended operations route through the ledger mechanism, maintaining state across multi-hour research tasks.

Frequently Asked Questions

What happens if a tool exceeds its configured timeout in Apache Maka?

When a subprocess exceeds its timeoutMs value, the host kernel forcibly terminates the process and updates the Task Ledger with a timeout status. The model receives this failure state via task_get, allowing it to inform the user or retry with adjusted parameters.

Can users cancel a tool that is already running for several minutes?

Yes. Apache Maka propagates cancellation signals through abort controllers stored in the host kernel. When a user aborts or the conversation turns timeout, the runtime triggers the abort controller associated with the pending task_create entry, immediately freeing system resources.

How does Apache Maka handle progress reporting for multi-hour tasks?

The runtime supports progressive result streaming through the Task Ledger. While executing, long-running tools can call task_update to append status messages or partial outputs. The model polls these updates using task_list or task_get, surfacing progress indicators without blocking the conversation flow.

What is the default timeout for tools in Apache Maka?

According to the host kernel implementation in packages/runtime-host/src/server/host-kernel.ts, most commands default to approximately 30 seconds. However, developers can override this default by specifying a custom timeoutMs value in the task_create payload, supporting execution windows that extend to hours.

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