Archived on 2026-07-13. These notes describe the initial Phase 1–4 skeleton; the backend architecture chapters and current source now describe the active runtime.
Status: Phase 1–4 skeleton landed (compile-safe, tested). The production SessionManager.sendMessage hot path is unchanged; the v2 seam exists in parallel so future work can migrate onto it incrementally.
Source plan: docs/archive/runtime-v2-architecture-evolution.md.
@maka/core)packages/core/src/runtime-event.ts — the canonical RuntimeEvent fact model (role / author / status enums, content discriminated union, actions, refs, pure helpers isTerminalRuntimeEvent / runtimeEventHasModelVisibleContent / createRuntimeEventId).packages/core/src/__tests__/runtime-event.test.ts — focused contract tests.@maka/core/runtime-event, plus a barrel re-export of the public surface from packages/core/src/index.ts.@maka/runtime)Five new modules, each importable via its canonical subpath AND re-exported (selectively) from the runtime barrel:
| Module | Subpath | Role |
|---|---|---|
runtime-event-adapters.ts | @maka/runtime/runtime-event-adapters | Legacy StoredMessage ↔ RuntimeEvent bridge (user/assistant/system_note text + thinking; tool/permission/tokenUsage return null). |
model-history.ts | @maka/runtime/model-history | Policy-driven buildModelHistoryFromRuntimeEvents() replacing ad-hoc StoredMessage filtering. |
invocation-context.ts | @maka/runtime/invocation-context | InvocationRequest / InvocationContext spine, injectable newId/now providers, InvocationResult envelope. |
runtime-runner.ts | @maka/runtime/runtime-runner | RuntimeRunner.run() collecting shell: preflight gate → context → user event → flow dispatch → terminal collection. |
agent-flow.ts | @maka/runtime/agent-flow | Formal AgentFlow / AgentFlowControl / FlowInput seam. |
ai-sdk-flow.ts | @maka/runtime/ai-sdk-flow | AiSdkFlow wrapping an AgentBackend; mapSessionEventToRuntimeEvent() placeholder mapping. |
Each module ships a co-located test suite (runtime-event-adapters.test.ts, runtime-runner.test.ts, ai-sdk-flow.test.ts).
packages/core/package.json — added "./runtime-event".packages/core/src/index.ts — re-exports the RuntimeEvent surface.packages/runtime/package.json — added six subpath exports.packages/runtime/src/index.ts — selective barrel re-exports.InvocationContext typeInvocationContext is now owned by invocation-context.ts and reused by the formal flow seam:
invocation-context.ts — the canonical runner/flow spine (required source, startedAt, request, newId, now).agent-flow.ts — imports and re-exports that canonical type for the AgentFlow.run(ctx, input) contract.The runtime barrel re-exports the canonical InvocationContext from invocation-context.ts; the previous duplicate flow-local context has been removed so runner and flow code share the same identity/provider spine.
tool_output_delta / tool_progress SessionEvents to a dedicated tool-progress runtime action (currently partial tool-role heartbeats). Refine mapSessionEventToRuntimeEvent role/author policy.RuntimeGate and inject it into desktop + bot/gateway entrypoints.StoredMessage / TurnRecord / SessionHeader / AgentRunStore / RunTrace / TelemetryRepo writes from InvocationResult.events. Wire buildModelHistoryFromRuntimeEvents() into the live AiSdkBackend.materializePriorMessages path.SessionManager.sendMessage with RuntimeRunner.run(...) behind a feature flag, mapping InvocationResult.events → existing SessionEvent projection. A streaming async *stream() variant may be added then if the renderer needs live deltas. Today RuntimeRunner.run() is collecting (returns Promise<InvocationResult>), not streaming.abort + complete coalescing: AiSdkFlow is a faithful translator (the backend emits abort then a trailing complete, and the flow emits both). Coalescing into a single terminal event is a runner/projection concern.RuntimeRunner depends on the centrally owned RunnableAgentFlow (Pick<AgentFlow, 'run'>) so it remains decoupled from flow metadata (kind, sessionId) while sharing the formal AgentFlow.run signature. The old AgentFlowLike name remains as a deprecated compatibility alias.All commands run from the repository root ($RIVE_WORKSPACE):
npm run build # all workspaces — clean npm run typecheck # all workspaces — clean npm --workspace @maka/core run test # 613 pass / 0 fail npm --workspace @maka/runtime run test # 384 pass / 0 fail git diff --check # clean
No production source (session-manager.ts, ai-sdk-backend.ts, agent-run.ts, materializer.ts) was modified. The v2 seam is purely additive.