Files
waggle-os/packages/agent/src/turn-context.ts
Oleg Maslov 0c3e2ead3b
Some checks failed
Installer Smoke / installer-smoke (push) Has been cancelled
moving
2026-09-02 10:10:29 +02:00

77 lines
2.7 KiB
TypeScript

/**
* H-AUDIT-1 contract — per-turn trace ID (turnId, UUID v4).
*
* turnId is generated ONCE at turn entry (chat.ts) and propagated EXPLICITLY
* as a parameter through every downstream stage: agent-loop → orchestrator
* recall → combined-retrieval search → prompt-assembler assemble →
* cognify (if triggered mid-turn) → tool calls → LLM request.
*
* No AsyncLocalStorage, no module-level context, no globals — propagation
* must be tsc-verifiable so a cold reader of any stage's signature can see
* whether trace is plumbed through it.
*
* Logging uses a shared pino logger tagged with `turnId`, so a single
* turnId in the log reconstructs the full turn graph (stage-by-stage with
* timestamps, input summary, output summary). This also doubles as the
* correlation key for the four-cell ablation harness JSONL output.
*
* Adoption rule: every stage entry function accepts `turnId?: string` as
* an optional parameter. Omitted = logging is silent (preserves existing
* callers that don't thread trace). When present, logs fire.
*/
import { randomUUID } from 'node:crypto';
import { createCoreLogger } from '@waggle/core';
const log = createCoreLogger('turn');
/** Generate a fresh per-turn trace ID. */
export function generateTurnId(): string {
return randomUUID();
}
export interface TurnLogPayload {
/** Stage label, e.g. 'orchestrator.recallMemory', 'retrieval.search'. */
stage: string;
[key: string]: unknown;
}
/**
* Emit a structured turn event. Silent when turnId is undefined
* (existing callers that haven't adopted trace propagation yet).
*
* Tests can opt into event capture via `startCapture()` below.
*/
export function logTurnEvent(turnId: string | undefined, payload: TurnLogPayload): void {
if (!turnId) return;
log.info(`turn.${payload.stage}`, { turnId, ...payload });
if (captureBuffer) {
captureBuffer.push({ turnId, ...payload });
}
}
// ── Test-only capture ────────────────────────────────────────────────────
export interface TurnEventRecord {
turnId: string;
stage: string;
[key: string]: unknown;
}
let captureBuffer: TurnEventRecord[] | null = null;
/**
* Start capturing turn events. Returns the buffer test code can assert on.
* Reset the buffer to capture fresh events — subsequent `startCapture`
* calls replace (not append to) the existing buffer.
*/
export function startTurnCapture(): TurnEventRecord[] {
captureBuffer = [];
return captureBuffer;
}
/** Stop capturing turn events. Events after this point go to the logger only. */
export function stopTurnCapture(): void {
captureBuffer = null;
}