maka/docs/archive/runtime-kernel.md

Runtime Kernel Extraction

Archived on 2026-07-13. This is a point-in-time extraction record, not current architecture authority. Start with ARCHITECTURE.md.

This document explains the runtime-kernel work in this change set: what changed, why it was needed, what stayed stable, and how it was verified.

Summary

Maka already had the pieces of a local desktop coding agent: sessions, model streams, tool calls, permission prompts, abort handling, usage telemetry, bot and gateway entry points, and persisted session messages. The problem was that the core execution responsibilities were still concentrated in a few large runtime paths, especially AiSdkBackend and SessionManager.sendMessage().

This change set keeps the product surfaces stable but introduces clearer internal runtime boundaries:

SessionManager
  -> AgentRun
      -> AiSdkBackend
          -> ModelAdapter
          -> ToolRuntime
      -> RunTrace
      -> AgentRunStore

The intent is not to rewrite the runtime or replace the Vercel AI SDK. The goal is to make the existing runtime easier to reason about, easier to recover after interruption, and easier to extend with future backends or workflow integrations.

What Changed

ToolRuntime

ToolRuntime is now the internal boundary for the lifecycle of model-requested tools. The extracted runtime owns the work that used to be interleaved inside the AI SDK backend:

• validate tool input before execution
• evaluate permission policy
• wait for parked permission decisions with timeout behavior
• pause and resume the stream watchdog around tool execution
• propagate abort signals into tools
• classify tool failures
• record tool telemetry and artifacts
• emit tool and permission trace events

AiSdkBackend still bridges model stream behavior, but it no longer needs to own every detail of tool execution.

ModelAdapter

ModelAdapter is the provider-facing stream and error normalization layer. It keeps AI SDK-specific stream chunks, provider setup, usage normalization, and provider error mapping out of the higher-level backend orchestration shell.

This makes the boundary explicit:

provider / AI SDK details
  -> ModelAdapter
  -> Maka runtime events and usage records

That separation matters because future providers should not need to duplicate permission, tool, run, or session-state behavior.

RunTrace

RunTrace is an internal best-effort trace path for runtime events. It records milestones such as:

• turn started
• model resolved / stream started / stream completed / stream failed
• tool started / completed / failed
• permission requested / decided / failed
• usage recorded
• abort requested

Trace recorder failures are intentionally non-fatal. A failed trace write must not alter model or tool execution.

AgentRun Types and Store

The core package now defines internal AgentRun contracts:

• AgentRunHeader
• AgentRunEvent
• AgentRunStatus
• AgentRunStore

The storage package adds a file-backed run store:

sessions/<sessionId>/runs/<runId>/run.json
sessions/<sessionId>/runs/<runId>/events.jsonl

The store provides:

• atomic run.json writes
• append-only run event JSONL
• same-run write serialization
• session run listing
• corrupt committed event-line recovery via event_corrupt
• malformed unterminated tail tolerance

This ledger is separate from the existing session message JSONL so runtime diagnostics and recovery state do not pollute user-visible conversation history.

AgentRun Execution

SessionManager.sendMessage() now delegates the heavy turn lifecycle to internal AgentRun.execute().

AgentRun owns:

• generating and recording run identity
• appending the user message
• writing initial turn state
• locking the connection snapshot for the run
• ensuring the active backend exists
• driving backend stream events
• projecting session status changes
• writing turn completion, failure, abort, or permission-wait states
• recording run started/completed/failed/cancelled status
• routing RunTrace events into the durable run ledger
• preserving abort source diagnostics such as renderer.stop_button

SessionManager remains the public runtime API and continues to own session CRUD, backend registry orchestration, active run lookup, and legacy recovery entry points.

Active Run Registry

The old active stream counters and turn-id side maps were replaced with:

activeRuns: Map<string, AgentRun>
turnToRunId: Map<string, string>

This makes overlapping run behavior explicit. It also avoids masking active stream accounting bugs with defensive counter clamping.

Startup Recovery

recoverInterruptedSessions() now prefers the AgentRun ledger when run rows are available. It scans persisted run headers and events, classifies stale non-terminal runs, repairs them, and then converges the existing session/turn projection.

Recovered cases include:

• stale created or running runs
• runs whose last event is run_started or model_stream_started
• stale tool tails after tool_started
• stale permission waits after permission_requested
• model_stream_completed without a terminal run event
• corrupt run event lines represented as event_corrupt

Legacy sessions without run ledger rows still use the prior message and turn-state recovery path.

What Stayed Stable

This work intentionally does not change:

• window.maka.* preload API
• Electron IPC channel names
• renderer-visible SessionEvent behavior
• user-visible permission modes
• session message JSONL compatibility
• builtin tool names or public tool behavior
• model provider settings UI
• bot and OpenGateway public entry points
• Rive workflow integration semantics

The runtime kernel is internal. Public behavior should remain compatible while the internals become more explicit and recoverable.

Why This Was Needed

Before this work, a single turn execution was spread across session management, backend stream handling, tool wrapping, permission policy, telemetry, and abort logic. That made several questions difficult to answer after a failure:

• Did the model stream start?
• Which backend/model/connection did the turn use?
• Was the run waiting for permission?
• Which tool was running when the app exited?
• Did the user press stop?
• Was usage recorded?
• Did a stale session status reflect a real active run or a crashed process?

The AgentRun ledger gives the runtime a durable fact record for those answers. ToolRuntime and ModelAdapter then reduce the amount of model/tool/provider logic that has to be understood at once.

Recovery Model

The new recovery path is conservative. It does not replay model streams or tools. Instead, it repairs stale state into deterministic terminal states so the app does not reopen with sessions permanently stuck in running or waiting_for_user.

When a stale non-terminal run is recovered, the runtime:

1. Updates the AgentRun header to terminal state.
2. Appends a durable recovery event such as run_failed or run_completed.
3. Writes the existing session turn_state projection.
4. Updates the session header out of active running/waiting states.

The failure class for app-restart recovery is recorded as app_restarted. Diagnostics are limited to small reason-code fields such as recovered, failureClass, recoveryReason, lastEventType, and eventCorrupt; raw user text and raw event payloads are not copied into recovery diagnostics.

Files Added

• packages/runtime/src/tool-runtime.ts
• packages/runtime/src/model-adapter.ts
• packages/runtime/src/run-trace.ts
• packages/core/src/agent-run.ts
• packages/storage/src/agent-run-store.ts
• packages/runtime/src/agent-run.ts
• packages/runtime/src/agent-run-recovery.ts

Tests Added or Expanded

The runtime test suite now covers:

• ToolRuntime permission allow/block/prompt/timeout paths
• watchdog pause/resume behavior around tools
• tool abort and failure classification behavior
• tool telemetry and artifact recording behavior
• ModelAdapter stream, usage, and provider error normalization
• RunTrace recording and best-effort failure behavior
• overlapping AgentRuns
• backend build failure after user-message append
• permission handoff without stuck run state
• stop button abort source preservation
• late complete after stop not overwriting aborted state
• durable trace redaction
• AgentRunStore create/read/update/list behavior
• same-run AgentRun event append serialization
• corrupt AgentRun event JSONL recovery
• startup recovery from stale AgentRun ledger states
• legacy startup recovery fallback
• terminal AgentRun recovery idempotency

Verification

The changes were verified with:

npm --workspace @maka/core run typecheck
npm --workspace @maka/storage run test
npm --workspace @maka/runtime run typecheck
npm --workspace @maka/runtime run test
npm --workspace @maka/desktop run build:main
git diff --check

The final runtime suite included 315 passing tests after the AgentRun recovery work.

Follow-Up Work

This PR establishes the internal runtime-kernel shape, but it does not finish every possible cleanup. Good follow-up slices are:

• merge usage and cost accounting more tightly with the run ledger
• expose an internal run-inspection/debug read model
• reduce the remaining SessionManager hook surface used by AgentRun
• consider Gateway/Bot policy unification through the same run policy layer
• consider Rive workflow/run mapping only after there is a product need