@iowarp/clio-coder 0.3.1 → 0.3.3

package/src/interactive/slash-spec.ts

@@ -1,17 +1,15 @@
 import type { SlashCommand } from "./slash-commands.js";
 
 export interface CommandFlagSpec {
-	/** Primary flag, e.g. "--target". */
+	/** Unique flag name, e.g. "--target". */
 	name: string;
-	/** Accepted synonyms, e.g. ["--worker-profile", "--worker"]. */
-	aliases?: ReadonlyArray<string>;
 	/** True when the flag consumes the next token as its value. */
 	takesValue?: boolean;
 	/** True when every occurrence should be retained instead of last-one-wins. */
 	repeatable?: boolean;
 	/** Closed set of legal values; parse failure produces the usage result. */
 	values?: ReadonlyArray<string>;
-	/** Usage placeholder, e.g. "profile" renders as `[--worker <profile>]`. */
+	/** Usage placeholder, e.g. "profile" renders as `[--agent-profile <profile>]`. */
 	valueName?: string;
 }
 
@@ -214,7 +212,7 @@ export function parseArgs(spec: CommandArgsSpec, argsLine: string): ParsedArgs {
 					const tokenStart = index;
 					const read = readToken();
 					if (read === null) break;
-					const matchedFlagSpec = flagSpecs.find((f) => f.name === read.token || f.aliases?.includes(read.token));
+					const matchedFlagSpec = flagSpecs.find((f) => f.name === read.token);
 					if (!matchedFlagSpec) {
 						index = tokenStart;
 						break;
@@ -242,7 +240,7 @@ export function parseArgs(spec: CommandArgsSpec, argsLine: string): ParsedArgs {
 		let matchedFlagSpec: CommandFlagSpec | undefined;
 
 		if (token.startsWith("--")) {
-			matchedFlagSpec = flagSpecs.find((f) => f.name === token || f.aliases?.includes(token));
+			matchedFlagSpec = flagSpecs.find((f) => f.name === token);
 			if (matchedFlagSpec) {
 				isFlag = true;
 			} else {
@@ -324,10 +322,7 @@ function walkCompletedTokens(spec: CommandArgsSpec, tokens: ReadonlyArray<string
 		}
 		const atRest = positionalSpecs[walk.positionalIndex]?.rest === true;
 		const flagsParseable = !atRest || spec.parseFlagsBeforeRest === true;
-		const matched =
-			flagsParseable && token.startsWith("--")
-				? flagSpecs.find((flag) => flag.name === token || flag.aliases?.includes(token))
-				: undefined;
+		const matched = flagsParseable && token.startsWith("--") ? flagSpecs.find((flag) => flag.name === token) : undefined;
 		if (matched) {
 			walk.usedFlags.add(matched.name);
 			if (matched.takesValue) walk.awaitingValue = matched;
@@ -344,14 +339,7 @@ function walkCompletedTokens(spec: CommandArgsSpec, tokens: ReadonlyArray<string
 
 function flagCompletions(spec: CommandArgsSpec, walk: CompletionWalk, current: string): ArgCompletion[] {
 	const available = (spec.flags ?? []).filter((flag) => flag.repeatable === true || !walk.usedFlags.has(flag.name));
-	let rows = available.filter((flag) => flag.name.startsWith(current)).map((flag) => ({ flag, name: flag.name }));
-	// When the typed token matches no primary name, fall back to aliases so a
-	// legal spelling like --rewrite still completes instead of going silent.
-	if (rows.length === 0) {
-		rows = available.flatMap((flag) =>
-			(flag.aliases ?? []).filter((alias) => alias.startsWith(current)).map((alias) => ({ flag, name: alias })),
-		);
-	}
+	const rows = available.filter((flag) => flag.name.startsWith(current)).map((flag) => ({ flag, name: flag.name }));
 	return rows.map(({ flag, name }) => ({
 		token: name,
 		...(flag.takesValue ? { hint: `<${getFlagValuePlaceholder(flag)}>` } : {}),
@@ -418,31 +406,14 @@ export function completeArgs(spec: CommandArgsSpec, argumentText: string): ArgCo
 export function matchFromSpec(
 	entry: {
 		name: string;
-		aliases?: ReadonlyArray<string>;
-		aliasArgs?: Readonly<Record<string, string>>;
 		args?: CommandArgsSpec;
 		fromArgs?: (parsed: ParsedArgs, trimmed: string) => SlashCommand;
 	},
 	trimmed: string,
 ): SlashCommand | null {
-	const nameOrAlias = [entry.name, ...(entry.aliases ?? [])];
-	let matchedPrefix: string | null = null;
-	let matchedTerm: string | null = null;
-	for (const term of nameOrAlias) {
-		const prefix = `/${term}`;
-		if (trimmed === prefix || trimmed.startsWith(`${prefix} `)) {
-			matchedPrefix = prefix;
-			matchedTerm = term;
-			break;
-		}
-	}
-	if (!matchedPrefix) return null;
-
-	// An alias that stands for a subcommand supplies that subcommand ahead of
-	// whatever was typed after it, so `/compact tidy up` parses as the line
-	// `/context compact tidy up` and reaches the same handler by the same route.
-	const implied = matchedTerm === null ? undefined : entry.aliasArgs?.[matchedTerm];
-	const argsLine = implied ? ` ${implied}${trimmed.slice(matchedPrefix.length)}` : trimmed.slice(matchedPrefix.length);
+	const matchedPrefix = `/${entry.name}`;
+	if (trimmed !== matchedPrefix && !trimmed.startsWith(`${matchedPrefix} `)) return null;
+	const argsLine = trimmed.slice(matchedPrefix.length);
 	const parsed = parseArgs(entry.args ?? {}, argsLine);
 
 	if (entry.fromArgs) {

package/src/interactive/status/controller.ts

@@ -181,7 +181,11 @@ export function createStatusController(deps: StatusControllerDeps): StatusContro
 	unsubscribes.push(
 		deps.chat.onEvent((event: ChatLoopEvent) => {
 			if (event.type === "agent_status") return;
-			apply(event);
+			// RunAborted publishes a provisional ended summary immediately. The
+			// terminal agent_end commonly follows inside the ordinary notification
+			// throttle, but its reconciled usage must still replace that provisional
+			// footer receipt.
+			apply(event, event.type === "agent_end");
 		}),
 	);
 

package/src/interactive/status/index.ts

@@ -1,13 +1,24 @@
 export type { StatusController, StatusControllerDeps } from "./controller.js";
 export { createStatusController } from "./controller.js";
+export {
+	compactReasoningTokens,
+	formatReasoningChip,
+	formatReasoningLabel,
+	type ReasoningProvenance,
+	type ReasoningUsageView,
+	reasoningFromSummary,
+	reasoningFromTally,
+	UNMEASURED_REASONING,
+} from "./reasoning.js";
 export { type ReduceContext, reduceStatus, type StatusInputEvent } from "./state-machine.js";
-export { type BuildSummaryInput, buildSummary } from "./summary.js";
+export { type BuildSummaryInput, buildSummary, emptyRunTally, foldMessageIntoRunTally } from "./summary.js";
 export {
 	type AgentStatus,
 	type AgentStatusChangedPayload,
 	type AgentStatusEvent,
 	INITIAL_STATUS,
 	type ReasoningTokenProvenance,
+	type RunTally,
 	type StatusPhase,
 	type TurnStopReason,
 	type TurnSummary,

package/src/interactive/status/reasoning.ts

@@ -0,0 +1,87 @@
+import type { ReasoningTokenProvenance, RunTally, TurnSummary } from "./types.js";
+
+/**
+ * One projection of a turn's reasoning spend for every surface that shows it.
+ *
+ * Reasoning counts used to be derived in three places (the status tally, the
+ * chat panel's own `message_end` re-derivation, and a chars/4 estimate over the
+ * visible thinking text), so the transcript, the turn receipt, and the footer
+ * could each report a different number for the same turn. Everything now reads
+ * `RunTally`/`TurnSummary` through this module, so a surface can differ in
+ * layout but never in the number or its provenance.
+ *
+ * `unmeasured` is a view-only state: nothing has been folded yet, so the count
+ * is unknown rather than zero. It never reaches `TurnSummary`, which keeps its
+ * persisted `provider | estimated | mixed` vocabulary.
+ */
+export type ReasoningProvenance = ReasoningTokenProvenance | "unmeasured";
+
+export interface ReasoningUsageView {
+	tokens: number;
+	provenance: ReasoningProvenance;
+}
+
+export const UNMEASURED_REASONING: ReasoningUsageView = { tokens: 0, provenance: "unmeasured" };
+
+function provenanceOf(hadProvider: boolean, hadEstimated: boolean): ReasoningProvenance {
+	if (hadProvider && hadEstimated) return "mixed";
+	if (hadProvider) return "provider";
+	if (hadEstimated) return "estimated";
+	return "unmeasured";
+}
+
+function finiteTokens(value: unknown): number {
+	return typeof value === "number" && Number.isFinite(value) ? Math.max(0, value) : 0;
+}
+
+/** Live view of the in-flight turn, folded message by message as the run settles. */
+export function reasoningFromTally(tally: RunTally | undefined): ReasoningUsageView {
+	if (!tally) return UNMEASURED_REASONING;
+	const provenance = provenanceOf(tally.hadProviderReasoning === true, tally.hadEstimatedReasoning === true);
+	if (provenance === "unmeasured") return UNMEASURED_REASONING;
+	return { tokens: finiteTokens(tally.reasoningTokens), provenance };
+}
+
+/** Settled view of a turn, including one replayed from a persisted summary. */
+export function reasoningFromSummary(summary: TurnSummary | undefined): ReasoningUsageView {
+	if (!summary || typeof summary.reasoningTokens !== "number") return UNMEASURED_REASONING;
+	// A summary persisted before provenance was recorded carries a count and no
+	// label. `summaryFromRunTally` writes both together, so this only covers
+	// replayed history, where the count came from provider usage.
+	return { tokens: finiteTokens(summary.reasoningTokens), provenance: summary.reasoningTokenProvenance ?? "provider" };
+}
+
+/**
+ * Compact token text for the surfaces that have no formatter of their own. The
+ * footer passes its own `formatFooterTokens` so its chips keep the width
+ * budget the rest of the footer is measured against.
+ */
+export function compactReasoningTokens(value: number): string {
+	if (value < 1000) return String(Math.round(value));
+	if (value < 1_000_000) {
+		const scaled = (value / 1000).toFixed(1);
+		return `${scaled.endsWith(".0") ? scaled.slice(0, -2) : scaled}k`;
+	}
+	const scaled = (value / 1_000_000).toFixed(1);
+	return `${scaled.endsWith(".0") ? scaled.slice(0, -2) : scaled}M`;
+}
+
+/**
+ * `r123` for a provider-attested count, `r≈123` for anything Clio inferred.
+ * Null when there is nothing to state: an unmeasured turn, or one that spent no
+ * reasoning tokens at all (a chip reading `r0` names the provenance of zero).
+ */
+export function formatReasoningChip(
+	view: ReasoningUsageView,
+	format: (value: number) => string = compactReasoningTokens,
+): string | null {
+	if (view.provenance === "unmeasured" || view.tokens <= 0) return null;
+	return `r${view.provenance === "provider" ? "" : "≈"}${format(view.tokens)}`;
+}
+
+export function formatReasoningLabel(view: ReasoningUsageView): string {
+	if (view.provenance === "provider") return "provider-reported";
+	if (view.provenance === "estimated") return "estimated";
+	if (view.provenance === "mixed") return "mixed";
+	return "unmeasured";
+}

package/src/interactive/status/summary.ts

@@ -18,6 +18,7 @@ interface UsageLike {
 	output?: number;
 	cacheRead?: number;
 	cacheWrite?: number;
+	estimated?: boolean;
 }
 
 function assistantThinkingText(message: AgentMessage): string {
@@ -91,7 +92,10 @@ export function foldMessageIntoRunTally(tally: RunTally, message: AgentMessage):
 		cacheReadTokens: tally.cacheReadTokens + (usage ? finite(usage.cacheRead) : 0),
 		cacheWriteTokens: tally.cacheWriteTokens + (usage ? finite(usage.cacheWrite) : 0),
 	};
-	const reasoning = usage ? extractReasoningTokens(usage) : null;
+	// Interrupted turns carry Clio's own estimated usage object. It retains the
+	// completed-record shape, including `reasoning: 0`, but that zero is not a
+	// provider attestation and must not suppress the thinking-text fallback.
+	const reasoning = usage && usage.estimated !== true ? extractReasoningTokens(usage) : null;
 	if (reasoning !== null) {
 		next.reasoningTokens += reasoning;
 		next.hadProviderReasoning = true;
@@ -102,7 +106,14 @@ export function foldMessageIntoRunTally(tally: RunTally, message: AgentMessage):
 	// reported as mixed rather than silently dropping the unreported block.
 	const estimated = estimateReasoningTextTokens(assistantThinkingText(message));
 	if (estimated !== null) {
-		next.reasoningTokens += estimated;
+		// A chars/4 estimate over displayed thinking text can outrun what the
+		// provider says the call generated (summarized reasoning, a rail that
+		// re-renders the same block). Reported output is the ceiling for anything
+		// inferred: reasoning is part of that output, never more than it. No
+		// clamp exists upstream in the adapters, so it lives here, once.
+		const reportedOutput =
+			usage && typeof usage.output === "number" && Number.isFinite(usage.output) ? Math.max(0, usage.output) : null;
+		next.reasoningTokens += reportedOutput === null ? estimated : Math.min(estimated, reportedOutput);
 		next.hadEstimatedReasoning = true;
 	}
 	return next;

package/src/interactive/stdout-backpressure.ts

@@ -0,0 +1,99 @@
+/**
+ * Process-wide stdout admission gate for interactive frame production.
+ *
+ * A terminal frame whose write returns false was accepted by Node, but the
+ * writable is now saturated. The current frame may finish its cursor/IME
+ * writes; later frames wait for drain and then render the newest model state.
+ */
+
+export interface StdoutBackpressureGate {
+	readonly blocked: boolean;
+	readonly observed: boolean;
+	onWritable(listener: () => void): () => void;
+	/** Resolve false when a finite wait expires; no listener survives the bound. */
+	whenWritable(timeoutMs?: number): Promise<boolean>;
+	restore(): void;
+}
+
+interface WritableStdoutBoundary {
+	write: typeof process.stdout.write;
+	once(event: "drain", listener: () => void): unknown;
+	off(event: "drain", listener: () => void): unknown;
+}
+
+export function installStdoutBackpressureGate(stdout: WritableStdoutBoundary = process.stdout): StdoutBackpressureGate {
+	const original = stdout.write;
+	const listeners = new Set<() => void>();
+	let blocked = false;
+	let observed = false;
+	let restored = false;
+	let drainListening = false;
+
+	const notifyWritable = (): void => {
+		drainListening = false;
+		if (!blocked) return;
+		blocked = false;
+		for (const listener of [...listeners]) listener();
+	};
+	const listenForDrain = (): void => {
+		if (drainListening || restored) return;
+		drainListening = true;
+		stdout.once("drain", notifyWritable);
+	};
+	const wrapped = function (this: typeof stdout, ...args: unknown[]): boolean {
+		const returned = Reflect.apply(original, this, args) as boolean;
+		if (!returned) {
+			observed = true;
+			blocked = true;
+			listenForDrain();
+		}
+		return returned;
+	} as typeof stdout.write;
+	stdout.write = wrapped;
+
+	return {
+		get blocked() {
+			return blocked;
+		},
+		get observed() {
+			return observed;
+		},
+		onWritable(listener) {
+			if (restored || !blocked) {
+				queueMicrotask(listener);
+				return () => {};
+			}
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		},
+		whenWritable(timeoutMs?: number) {
+			if (restored || !blocked) return Promise.resolve(true);
+			return new Promise<boolean>((resolve) => {
+				let timer: ReturnType<typeof setTimeout> | undefined;
+				const release = this.onWritable(() => {
+					if (timer) clearTimeout(timer);
+					release();
+					resolve(true);
+				});
+				if (timeoutMs !== undefined && Number.isFinite(timeoutMs) && timeoutMs >= 0) {
+					timer = setTimeout(() => {
+						release();
+						resolve(false);
+					}, timeoutMs);
+				}
+			});
+		},
+		restore() {
+			if (restored) return;
+			restored = true;
+			blocked = false;
+			if (drainListening) {
+				stdout.off("drain", notifyWritable);
+				drainListening = false;
+			}
+			if (stdout.write === wrapped) stdout.write = original;
+			for (const listener of [...listeners]) listener();
+			listeners.clear();
+		},
+	};
+}