@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/engine/gemma-channel-filter.ts

@@ -0,0 +1,223 @@
+import type {
+	AssistantMessage,
+	AssistantMessageEvent,
+	AssistantMessageEventStream,
+	TextContent,
+	ThinkingContent,
+} from "@earendil-works/pi-ai";
+import { createAssistantMessageEventStream } from "@earendil-works/pi-ai";
+
+const THOUGHT_START = /<\|channel>[^\n]*\n/;
+const BARE_THOUGHT_START = /^\s*(?:thought|own[- ]?(?:thought|think))\s*\n/i;
+const BARE_THOUGHT_ONLY = /^\s*(?:thought|own[- ]?(?:thought|think))\s*$/i;
+const THOUGHT_END = "<channel|>";
+const TOOL_CALL_START = "<tool_call|>";
+const TOOL_CALL_END = "<|tool_call|>";
+const LOOKAHEAD_BYTES = 64;
+
+export interface GemmaChannelSegment {
+	kind: "text" | "thinking";
+	content: string;
+}
+
+export interface GemmaChannelFilter {
+	push(chunk: string): GemmaChannelSegment[];
+	flush(): GemmaChannelSegment[];
+}
+
+function boundedPrefix(value: string): { prefix: string; tail: string } {
+	let tailStart = value.length;
+	while (tailStart > 0) {
+		const candidate = tailStart - 1;
+		if (Buffer.byteLength(value.slice(candidate), "utf8") > LOOKAHEAD_BYTES) break;
+		tailStart = candidate;
+	}
+	return { prefix: value.slice(0, tailStart), tail: value.slice(tailStart) };
+}
+
+export function createGemmaChannelFilter(): GemmaChannelFilter {
+	let pending = "";
+	let state: "idle" | "thought" | "toolcall" = "idle";
+	const route = (chunk: string): GemmaChannelSegment[] => {
+		const output: GemmaChannelSegment[] = [];
+		const emit = (kind: GemmaChannelSegment["kind"], content: string) => {
+			if (!content) return;
+			const previous = output.at(-1);
+			if (previous?.kind === kind) previous.content += content;
+			else output.push({ kind, content });
+		};
+		pending += chunk;
+		while (true) {
+			if (state === "thought") {
+				const end = pending.indexOf(THOUGHT_END);
+				const toolCall = pending.indexOf(TOOL_CALL_START);
+				if (toolCall >= 0 && (end < 0 || toolCall < end)) {
+					emit("thinking", pending.slice(0, toolCall));
+					pending = pending.slice(toolCall + TOOL_CALL_START.length);
+					state = "toolcall";
+					continue;
+				}
+				if (end >= 0) {
+					emit("thinking", pending.slice(0, end));
+					pending = pending.slice(end + THOUGHT_END.length);
+					state = "idle";
+					continue;
+				}
+				const bounded = boundedPrefix(pending);
+				emit("thinking", bounded.prefix);
+				pending = bounded.tail;
+				return output;
+			}
+			if (state === "toolcall") {
+				const end = pending.indexOf(TOOL_CALL_END);
+				if (end >= 0) {
+					pending = pending.slice(end + TOOL_CALL_END.length);
+					state = "idle";
+					continue;
+				}
+				pending = boundedPrefix(pending).tail;
+				return output;
+			}
+			const thought = THOUGHT_START.exec(pending);
+			const bare = BARE_THOUGHT_START.exec(pending);
+			const candidates = [
+				{ index: thought?.index ?? -1, kind: "thought" as const, length: thought?.[0].length ?? 0 },
+				{ index: bare ? 0 : -1, kind: "thought" as const, length: bare?.[0].length ?? 0 },
+				{ index: pending.indexOf(TOOL_CALL_START), kind: "toolcall" as const, length: TOOL_CALL_START.length },
+				{ index: pending.indexOf(THOUGHT_END), kind: "orphan" as const, length: THOUGHT_END.length },
+			]
+				.filter((candidate) => candidate.index >= 0)
+				.sort((left, right) => left.index - right.index);
+			const next = candidates[0];
+			if (!next) {
+				const bounded = boundedPrefix(pending);
+				emit("text", bounded.prefix);
+				pending = bounded.tail;
+				return output;
+			}
+			emit("text", pending.slice(0, next.index));
+			pending = pending.slice(next.index + next.length);
+			if (next.kind === "thought") state = "thought";
+			else if (next.kind === "toolcall") state = "toolcall";
+		}
+	};
+	return {
+		push: route,
+		flush() {
+			const output: GemmaChannelSegment[] = [];
+			if (state === "thought" && pending) output.push({ kind: "thinking", content: pending });
+			else if (state === "idle" && pending && !BARE_THOUGHT_ONLY.test(pending)) {
+				output.push({ kind: "text", content: pending });
+			}
+			pending = "";
+			state = "idle";
+			return output;
+		},
+	};
+}
+
+type ReplacementBlock = TextContent | ThinkingContent;
+
+export function filterGemmaChannelStream(
+	source: AssistantMessageEventStream,
+	enabled: boolean,
+): AssistantMessageEventStream {
+	if (!enabled) return source;
+	const filtered = createAssistantMessageEventStream();
+	const replacements = new Map<number, ReplacementBlock[]>();
+	const filters = new Map<number, GemmaChannelFilter>();
+	const activeKinds = new Map<number, GemmaChannelSegment["kind"]>();
+
+	const projectContent = (content: AssistantMessage["content"]): AssistantMessage["content"] =>
+		content.flatMap((block, index) => replacements.get(index) ?? [block]);
+	const projectMessage = (message: AssistantMessage): AssistantMessage => ({
+		...message,
+		content: projectContent(message.content),
+	});
+	const projectedIndex = (originalIndex: number, localIndex = 0): number => {
+		let offset = 0;
+		for (let index = 0; index < originalIndex; index += 1) offset += (replacements.get(index)?.length ?? 1) - 1;
+		return originalIndex + offset + localIndex;
+	};
+	const projectedPartial = (event: { partial: AssistantMessage }): AssistantMessage => projectMessage(event.partial);
+
+	(async () => {
+		try {
+			const closeActive = (originalIndex: number, partial: AssistantMessage) => {
+				const kind = activeKinds.get(originalIndex);
+				const blocks = replacements.get(originalIndex) ?? [];
+				const localIndex = blocks.length - 1;
+				const block = blocks[localIndex];
+				if (!kind || !block) return;
+				const contentIndex = projectedIndex(originalIndex, localIndex);
+				if (kind === "text" && block.type === "text") {
+					filtered.push({ type: "text_end", contentIndex, content: block.text, partial: projectMessage(partial) });
+				} else if (kind === "thinking" && block.type === "thinking") {
+					filtered.push({ type: "thinking_end", contentIndex, content: block.thinking, partial: projectMessage(partial) });
+				}
+				activeKinds.delete(originalIndex);
+			};
+			const emitSegments = (originalIndex: number, partial: AssistantMessage, segments: GemmaChannelSegment[]) => {
+				for (const segment of segments) {
+					if (activeKinds.get(originalIndex) !== segment.kind) {
+						closeActive(originalIndex, partial);
+						const blocks = replacements.get(originalIndex) ?? [];
+						blocks.push(segment.kind === "text" ? { type: "text", text: "" } : { type: "thinking", thinking: "" });
+						replacements.set(originalIndex, blocks);
+						activeKinds.set(originalIndex, segment.kind);
+						const contentIndex = projectedIndex(originalIndex, blocks.length - 1);
+						filtered.push({
+							type: segment.kind === "text" ? "text_start" : "thinking_start",
+							contentIndex,
+							partial: projectMessage(partial),
+						});
+					}
+					const blocks = replacements.get(originalIndex) ?? [];
+					const localIndex = blocks.length - 1;
+					const block = blocks[localIndex];
+					if (!block) continue;
+					if (segment.kind === "text" && block.type === "text") block.text += segment.content;
+					if (segment.kind === "thinking" && block.type === "thinking") block.thinking += segment.content;
+					filtered.push({
+						type: segment.kind === "text" ? "text_delta" : "thinking_delta",
+						contentIndex: projectedIndex(originalIndex, localIndex),
+						delta: segment.content,
+						partial: projectMessage(partial),
+					});
+				}
+			};
+
+			for await (const event of source) {
+				if (event.type === "text_start") {
+					replacements.set(event.contentIndex, []);
+					filters.set(event.contentIndex, createGemmaChannelFilter());
+					continue;
+				}
+				if (event.type === "text_delta") {
+					emitSegments(event.contentIndex, event.partial, filters.get(event.contentIndex)?.push(event.delta) ?? []);
+					continue;
+				}
+				if (event.type === "text_end") {
+					emitSegments(event.contentIndex, event.partial, filters.get(event.contentIndex)?.flush() ?? []);
+					closeActive(event.contentIndex, event.partial);
+					filters.delete(event.contentIndex);
+					continue;
+				}
+				if (event.type === "done") filtered.push({ ...event, message: projectMessage(event.message) });
+				else if (event.type === "error") filtered.push({ ...event, error: projectMessage(event.error) });
+				else if ("partial" in event) {
+					const contentIndex = "contentIndex" in event ? projectedIndex(event.contentIndex as number) : undefined;
+					filtered.push({
+						...event,
+						...(contentIndex === undefined ? {} : { contentIndex }),
+						partial: projectedPartial(event),
+					} as AssistantMessageEvent);
+				} else filtered.push(event as AssistantMessageEvent);
+			}
+			filtered.end();
+		} catch {
+			filtered.end();
+		}
+	})();
+	return filtered;
+}

package/src/engine/harmony-response.ts

@@ -0,0 +1,165 @@
+/**
+ * Streaming parser for OpenAI Harmony response markers used by GPT-OSS.
+ *
+ * Some local OpenAI-compatible servers return the model's raw chat-template
+ * text instead of normalized `content` / `reasoning_content` fields. In that
+ * mode GPT-OSS can leak markers like
+ * `<|start|>assistant<|channel|>final<|message|>` into visible output. This
+ * parser consumes those markers and routes channel payloads into Clio's text
+ * or thinking streams.
+ */
+
+import {
+	type HarmonyReasoningEffort,
+	harmonyReasoningEffort,
+	isHarmonyThinkingFormat,
+} from "../domains/providers/model-runtime-capabilities.js";
+
+const START = "<|start|>";
+const CHANNEL = "<|channel|>";
+const CONSTRAIN = "<|constrain|>";
+const MESSAGE = "<|message|>";
+const RECIPIENT = "<|recipient|>";
+const END = "<|end|>";
+const RETURN = "<|return|>";
+
+const MARKERS: ReadonlyArray<string> = [START, CHANNEL, CONSTRAIN, MESSAGE, RECIPIENT, END, RETURN];
+const HEADER_METADATA_MARKERS: ReadonlyArray<string> = [CONSTRAIN, RECIPIENT];
+const MAX_MARKER_LENGTH = MARKERS.reduce((max, marker) => Math.max(max, marker.length), 0);
+
+export interface HarmonyParsedChunk {
+	text: string;
+	thinking: string;
+}
+
+type HarmonyRoute = "text" | "thinking";
+
+export { type HarmonyReasoningEffort, harmonyReasoningEffort, isHarmonyThinkingFormat };
+
+export class HarmonyResponseParser {
+	private buffer = "";
+	private route: HarmonyRoute = "text";
+
+	push(chunk: string): HarmonyParsedChunk {
+		if (!chunk) return emptyParsed();
+		this.buffer += chunk;
+		return this.drain(false);
+	}
+
+	flush(): HarmonyParsedChunk {
+		return this.drain(true);
+	}
+
+	private drain(final: boolean): HarmonyParsedChunk {
+		let text = "";
+		let thinking = "";
+		const emit = (value: string): void => {
+			if (!value) return;
+			if (this.route === "thinking") thinking += value;
+			else text += value;
+		};
+
+		while (this.buffer.length > 0) {
+			const parsedFrame = this.consumeFrameHeader();
+			if (parsedFrame) continue;
+
+			if (this.consumeExact(END) || this.consumeExact(RETURN)) continue;
+
+			const markerIndex = firstMarkerIndex(this.buffer);
+			if (markerIndex > 0) {
+				emit(this.buffer.slice(0, markerIndex));
+				this.buffer = this.buffer.slice(markerIndex);
+				continue;
+			}
+
+			if (markerIndex === 0) {
+				if (!final) break;
+				// Unknown complete-ish marker at end of stream: drop only the
+				// marker bytes and preserve following ordinary text if any.
+				const marker = MARKERS.find((candidate) => this.buffer.startsWith(candidate));
+				if (!marker) break;
+				this.buffer = this.buffer.slice(marker.length);
+				continue;
+			}
+
+			const hold = final ? 0 : harmonyPrefixTailLength(this.buffer);
+			const emitLength = this.buffer.length - hold;
+			if (emitLength <= 0) break;
+			emit(this.buffer.slice(0, emitLength));
+			this.buffer = this.buffer.slice(emitLength);
+		}
+
+		if (final && this.buffer.length > 0) {
+			emit(this.buffer);
+			this.buffer = "";
+		}
+
+		return { text, thinking };
+	}
+
+	private consumeFrameHeader(): boolean {
+		if (this.buffer.startsWith(START)) {
+			const channelIndex = this.buffer.indexOf(CHANNEL, START.length);
+			if (channelIndex === -1) return false;
+			const messageIndex = this.buffer.indexOf(MESSAGE, channelIndex + CHANNEL.length);
+			if (messageIndex === -1) return false;
+			this.setChannel(this.buffer.slice(channelIndex + CHANNEL.length, messageIndex));
+			this.buffer = this.buffer.slice(messageIndex + MESSAGE.length);
+			return true;
+		}
+
+		if (this.buffer.startsWith(CHANNEL)) {
+			const messageIndex = this.buffer.indexOf(MESSAGE, CHANNEL.length);
+			if (messageIndex === -1) return false;
+			this.setChannel(this.buffer.slice(CHANNEL.length, messageIndex));
+			this.buffer = this.buffer.slice(messageIndex + MESSAGE.length);
+			return true;
+		}
+
+		return false;
+	}
+
+	private consumeExact(marker: string): boolean {
+		if (!this.buffer.startsWith(marker)) return false;
+		this.buffer = this.buffer.slice(marker.length);
+		return true;
+	}
+
+	private setChannel(rawChannel: string): void {
+		const metadataIndex = firstHeaderMetadataIndex(rawChannel);
+		const channelText = metadataIndex === -1 ? rawChannel : rawChannel.slice(0, metadataIndex);
+		const channel = (channelText.trim().split(/\s+/, 1)[0] ?? "").toLowerCase();
+		this.route = channel === "final" ? "text" : "thinking";
+	}
+}
+
+function emptyParsed(): HarmonyParsedChunk {
+	return { text: "", thinking: "" };
+}
+
+function firstMarkerIndex(value: string): number {
+	let first = -1;
+	for (const marker of MARKERS) {
+		const idx = value.indexOf(marker);
+		if (idx !== -1 && (first === -1 || idx < first)) first = idx;
+	}
+	return first;
+}
+
+function firstHeaderMetadataIndex(value: string): number {
+	let first = -1;
+	for (const marker of HEADER_METADATA_MARKERS) {
+		const idx = value.indexOf(marker);
+		if (idx !== -1 && (first === -1 || idx < first)) first = idx;
+	}
+	return first;
+}
+
+function harmonyPrefixTailLength(value: string): number {
+	const max = Math.min(value.length, MAX_MARKER_LENGTH - 1);
+	for (let len = max; len > 0; len--) {
+		const tail = value.slice(value.length - len);
+		if (MARKERS.some((marker) => marker.startsWith(tail))) return len;
+	}
+	return 0;
+}

package/src/engine/instrumented-tui.ts

@@ -0,0 +1,192 @@
+/**
+ * Render-transaction hooks around pi-tui's two concrete renderers.
+ *
+ * pi-tui deliberately exposes `doRender`, overlay composition, and line
+ * normalization as protected seams. Clio uses those seams instead of
+ * inferring frames from terminal writes: one `doRender()` is one frame, while
+ * any number of terminal writes (including the regular renderer's IME cursor
+ * write) can belong to that frame.
+ */
+
+import { type Terminal, TuiAltScreen, type TuiAltScreenOptions, TuiMainScreen } from "@earendil-works/pi-tui";
+
+export type TuiRenderPhase = "overlay" | "normalization" | "cursor";
+
+export interface TuiRenderObserver {
+	/** Optional fast-path used after a one-shot observer has delivered its frame. */
+	isEnabled?(): boolean;
+	beginFrame(fields: { mode: "regular" | "fullscreen"; columns: number; rows: number }): unknown;
+	endFrame(frame: unknown): void;
+	beginPhase(frame: unknown, phase: TuiRenderPhase): unknown;
+	endPhase(frame: unknown, phase: TuiRenderPhase, phaseToken: unknown): void;
+}
+
+export interface TuiRenderAdmission {
+	readonly blocked: boolean;
+	onWritable(listener: () => void): () => void;
+}
+
+class DeferredRenderAdmission {
+	private pending = false;
+	private force = false;
+	private release: (() => void) | null = null;
+
+	constructor(
+		private readonly admission: TuiRenderAdmission | undefined,
+		private readonly render: (force: boolean) => void,
+	) {}
+
+	request(force: boolean): boolean {
+		if (!this.admission?.blocked) return false;
+		this.pending = true;
+		this.force ||= force;
+		this.release ??= this.admission.onWritable(() => {
+			this.release?.();
+			this.release = null;
+			if (!this.pending) return;
+			const pendingForce = this.force;
+			this.pending = false;
+			this.force = false;
+			this.render(pendingForce);
+		});
+		return true;
+	}
+
+	/** A direct/final render supersedes any older request held behind the gate. */
+	settled(): void {
+		this.pending = false;
+		this.force = false;
+		this.release?.();
+		this.release = null;
+	}
+}
+
+export class InstrumentedTuiMainScreen extends TuiMainScreen {
+	constructor(
+		terminal: Terminal,
+		private readonly renderObserver: TuiRenderObserver,
+		showHardwareCursor?: boolean,
+		logDirectory?: string,
+		renderAdmission?: TuiRenderAdmission,
+	) {
+		super(terminal, showHardwareCursor, logDirectory);
+		this.deferredAdmission = new DeferredRenderAdmission(renderAdmission, (force) => super.requestRender(force));
+	}
+
+	override requestRender(force = false): void {
+		if (!this.deferredAdmission.request(force)) super.requestRender(force);
+	}
+
+	protected override doRender(): void {
+		this.deferredAdmission.settled();
+		if (this.renderObserver.isEnabled?.() === false) {
+			super.doRender();
+			return;
+		}
+		const frame = this.renderObserver.beginFrame({
+			mode: this.mode,
+			columns: this.terminal.columns,
+			rows: this.terminal.rows,
+		});
+		this.currentFrame = frame;
+		try {
+			super.doRender();
+		} finally {
+			this.currentFrame = undefined;
+			this.renderObserver.endFrame(frame);
+		}
+	}
+
+	protected override compositeOverlays(lines: string[], termWidth: number, termHeight: number): string[] {
+		return this.measure("overlay", () => super.compositeOverlays(lines, termWidth, termHeight));
+	}
+
+	protected override applyLineResets(lines: string[]): string[] {
+		return this.measure("normalization", () => super.applyLineResets(lines));
+	}
+
+	protected override extractCursorPosition(lines: string[], height: number): { row: number; col: number } | null {
+		return this.measure("cursor", () => super.extractCursorPosition(lines, height));
+	}
+
+	private measure<T>(phase: TuiRenderPhase, operation: () => T): T {
+		if (this.renderObserver.isEnabled?.() === false) return operation();
+		const frame = this.currentFrame;
+		if (frame === undefined) return operation();
+		const phaseToken = this.renderObserver.beginPhase(frame, phase);
+		try {
+			return operation();
+		} finally {
+			this.renderObserver.endPhase(frame, phase, phaseToken);
+		}
+	}
+
+	private currentFrame: unknown | undefined;
+	private readonly deferredAdmission: DeferredRenderAdmission;
+}
+
+export class InstrumentedTuiAltScreen extends TuiAltScreen {
+	private currentFrame: unknown | undefined;
+
+	constructor(
+		terminal: Terminal,
+		private readonly renderObserver: TuiRenderObserver,
+		showHardwareCursor?: boolean,
+		logDirectory?: string,
+		options?: TuiAltScreenOptions,
+		renderAdmission?: TuiRenderAdmission,
+	) {
+		super(terminal, showHardwareCursor, logDirectory, options);
+		this.deferredAdmission = new DeferredRenderAdmission(renderAdmission, (force) => super.requestRender(force));
+	}
+
+	override requestRender(force = false): void {
+		if (!this.deferredAdmission.request(force)) super.requestRender(force);
+	}
+
+	protected override doRender(): void {
+		this.deferredAdmission.settled();
+		if (this.renderObserver.isEnabled?.() === false) {
+			super.doRender();
+			return;
+		}
+		const frame = this.renderObserver.beginFrame({
+			mode: this.mode,
+			columns: this.terminal.columns,
+			rows: this.terminal.rows,
+		});
+		this.currentFrame = frame;
+		try {
+			super.doRender();
+		} finally {
+			this.currentFrame = undefined;
+			this.renderObserver.endFrame(frame);
+		}
+	}
+
+	protected override compositeOverlays(lines: string[], termWidth: number, termHeight: number): string[] {
+		return this.measure("overlay", () => super.compositeOverlays(lines, termWidth, termHeight));
+	}
+
+	protected override applyLineResets(lines: string[]): string[] {
+		return this.measure("normalization", () => super.applyLineResets(lines));
+	}
+
+	protected override extractCursorPosition(lines: string[], height: number): { row: number; col: number } | null {
+		return this.measure("cursor", () => super.extractCursorPosition(lines, height));
+	}
+
+	private measure<T>(phase: TuiRenderPhase, operation: () => T): T {
+		if (this.renderObserver.isEnabled?.() === false) return operation();
+		const frame = this.currentFrame;
+		if (frame === undefined) return operation();
+		const phaseToken = this.renderObserver.beginPhase(frame, phase);
+		try {
+			return operation();
+		} finally {
+			this.renderObserver.endPhase(frame, phase, phaseToken);
+		}
+	}
+
+	private readonly deferredAdmission: DeferredRenderAdmission;
+}