From c48d8ac7160c3cdcf32ed4e488807d3daeb8d457 Mon Sep 17 00:00:00 2001
From: Adam Malczewski <github@tradam.dev>
Date: Fri, 5 Jun 2026 13:07:23 +0900
Subject: feat(observability): Phase A logging substrate — Logger/Span ABI +
 journal sink (250 tests)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Structured, agent-first logging captured durably to an append-only journal file.

Kernel (contracts/logging.ts): leveled/attributed Logger + Span, auto-scoped per extension (host stamps manifest.id, unspoofable), incremental span records (open/close) for crash-reconstructable traces, injected LogSink (pure record-builder). ctx.log on ToolContract; runTurn opens turn/step/tool-call spans and captures the verbatim pre-mutation prompt (the 'before') on the step span.

journal-sink (new package, bootstrap dep — not an extension): LogSink appending NDJSON to a rotating journal; pure serialize + thin fs edge; fail-safe drop, never blocks a turn. host-bin injects it via HostDeps; session-orchestrator threads host.logger (childed per turn) into runTurn.

Redaction is per-extension self-redaction (no shared helper — isolation over DRY). The out-of-process collector + SQLite store + the verbatim 'after' provider.request capture are Phase B / next (notes/observability-design.md §10/§11).

Verified: tsc -b clean, 250 tests (218→+32), biome clean. Live boot: a turn's journal holds host logs + turn/step spans (open+close) + the prompt:before record with the verbatim messages array.

Harness: ORCHESTRATOR §3 rule-scoping map; .dispatch/rules/isolation-over-dry.md; notes/observability-design.md (design D1–D10 + Phase A/B plan).
---
 packages/kernel/src/runtime/dispatch.ts | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

(limited to 'packages/kernel/src/runtime/dispatch.ts')

diff --git a/packages/kernel/src/runtime/dispatch.ts b/packages/kernel/src/runtime/dispatch.ts
index 626b333..1ba0849 100644
--- a/packages/kernel/src/runtime/dispatch.ts
+++ b/packages/kernel/src/runtime/dispatch.ts
@@ -1,4 +1,5 @@
 import type { ToolDispatchPolicy } from "../contracts/dispatch.js";
+import type { Logger, Span } from "../contracts/logging.js";
 import type { EventEmitter } from "../contracts/runtime.js";
 import type { ToolCall, ToolContract, ToolExecuteContext, ToolResult } from "../contracts/tool.js";
 import { toolOutputEvent } from "./events.js";
@@ -15,6 +16,7 @@ export async function executeToolCall(
 	emit: EventEmitter,
 	conversationId: string,
 	turnId: string,
+	toolSpan?: Span,
 ): Promise<ToolResult> {
 	if (tool === undefined) {
 		return { content: `Unknown tool: ${call.name}`, isError: true };
@@ -28,6 +30,7 @@ export async function executeToolCall(
 		onOutput: (data, stream) => {
 			emit(toolOutputEvent(conversationId, turnId, call.id, data, stream));
 		},
+		log: toolSpan?.log ?? createNoopLogger(),
 	};
 	try {
 		return await tool.execute(call.input, ctx);
@@ -50,6 +53,7 @@ export function createStepDispatcher(
 	emit: EventEmitter,
 	conversationId: string,
 	turnId: string,
+	toolSpans: Map<string, Span>,
 ): StepDispatcher {
 	let activeCount = 0;
 	let unsafeRunning = false;
@@ -78,6 +82,7 @@ export function createStepDispatcher(
 	}
 
 	async function runAndResolve(entry: QueueEntry): Promise<void> {
+		const tcSpan = toolSpans.get(entry.call.id);
 		const result = await executeToolCall(
 			entry.call,
 			entry.tool,
@@ -85,6 +90,7 @@ export function createStepDispatcher(
 			emit,
 			conversationId,
 			turnId,
+			tcSpan,
 		);
 		activeCount--;
 		if (entry.tool?.concurrencySafe === false) unsafeRunning = false;
@@ -129,3 +135,27 @@ export function createStepDispatcher(
 
 	return { submit, drain };
 }
+
+function createNoopLogger(): Logger {
+	return {
+		debug() {},
+		info() {},
+		warn() {},
+		error() {},
+		child() {
+			return createNoopLogger();
+		},
+		span() {
+			return {
+				id: "noop",
+				log: createNoopLogger(),
+				setAttributes() {},
+				addLink() {},
+				child() {
+					return this;
+				},
+				end() {},
+			};
+		},
+	};
+}
-- 
cgit v1.2.3