@iowarp/clio-coder 0.3.2 → 0.3.3

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/transcript-detail.ts

@@ -0,0 +1,120 @@
+/**
+ * Transcript detail policy: the one place `/output minimal|default|verbose`
+ * becomes a decision about how much of each foldable transcript block is open
+ * before the operator touches it.
+ *
+ * The chat panel used to consult the verbosity string in four places, each
+ * spelling the rule a little differently, and nothing else (running rows, live
+ * tool output, worker cards in replay) consulted it at all. The panel now reads
+ * this policy once per frame and threads it down; the verbosity string never
+ * reaches a renderer.
+ *
+ * Operator toggles (`Alt+O`, `Alt+R`, expand-all, collapse-all) are overrides
+ * layered on top of this policy, not fights with it: the effective state of a
+ * block is `override ?? policy`, and `resolveFold` is that one rule.
+ *
+ * Pure module: no I/O, no UI imports.
+ */
+
+import type { OutputVerbosity } from "../core/defaults.js";
+import type { ToolFoldDefault, ToolPresentationPolicy } from "../tools/presentation.js";
+
+/** A block's fold state. The same vocabulary serves tools, workers, thinking, and local bash. */
+export type Fold = ToolFoldDefault;
+
+/** An operator's explicit choice for one block, or none. */
+export type FoldOverride = Fold | undefined;
+
+export interface TranscriptDetailPolicy {
+	/** Finished tool call body: folded subline, the tool's own default, or open. */
+	toolBody: "folded" | "per-tool" | "expanded";
+	/** In-flight tool call: one-line row with elapsed, or the header plus streaming body. */
+	runningTool: "row" | "body";
+	/** Reasoning stretch: bare marker, folded marker with live progress, or the open rail. */
+	thinking: "marker" | "folded" | "rail";
+	/** Worker block: folded card, the origin default, or open. */
+	worker: "folded" | "origin" | "expanded";
+	/** Settled turn receipt: none, `turn · in N · out M`, or the full receipt. */
+	receipt: "none" | "compact" | "full";
+	/** Failed tool under its folded row: the bounded excerpt, or the full body. */
+	errors: "excerpt" | "body";
+}
+
+const MINIMAL: TranscriptDetailPolicy = {
+	toolBody: "folded",
+	runningTool: "row",
+	thinking: "marker",
+	worker: "folded",
+	receipt: "none",
+	errors: "excerpt",
+};
+
+const DEFAULT: TranscriptDetailPolicy = {
+	toolBody: "per-tool",
+	runningTool: "row",
+	thinking: "folded",
+	worker: "origin",
+	receipt: "compact",
+	errors: "excerpt",
+};
+
+const VERBOSE: TranscriptDetailPolicy = {
+	toolBody: "expanded",
+	runningTool: "body",
+	thinking: "rail",
+	worker: "expanded",
+	receipt: "full",
+	errors: "body",
+};
+
+/**
+ * Map a verbosity to the full policy table. An absent verbosity (a panel built
+ * without settings) is the balanced default, so the literal never has to be
+ * spelled by the caller.
+ */
+export function transcriptDetail(verbosity: OutputVerbosity | undefined): TranscriptDetailPolicy {
+	switch (verbosity) {
+		case "minimal":
+			return MINIMAL;
+		case "verbose":
+			return VERBOSE;
+		default:
+			return DEFAULT;
+	}
+}
+
+/** Effective state of one block: the operator's override when set, else the policy's answer. */
+export function resolveFold(override: FoldOverride, policyFold: Fold): Fold {
+	return override ?? policyFold;
+}
+
+/** The fold the policy gives a finished tool call, through the tool's own presentation when asked to. */
+export function policyToolFold(detail: TranscriptDetailPolicy, presentation: ToolPresentationPolicy): Fold {
+	if (detail.toolBody === "per-tool") return presentation.foldDefault;
+	return detail.toolBody;
+}
+
+/** The fold the policy gives an in-flight tool call. */
+export function policyRunningToolFold(detail: TranscriptDetailPolicy): Fold {
+	return detail.runningTool === "body" ? "expanded" : "folded";
+}
+
+/** The fold the policy gives a reasoning stretch. */
+export function policyThinkingFold(detail: TranscriptDetailPolicy): Fold {
+	return detail.thinking === "rail" ? "expanded" : "folded";
+}
+
+/**
+ * The fold the policy gives a worker block. `askedByModel` is the origin rule
+ * the caller already knows: a run the model asked for folds, the operator's own
+ * run opens.
+ */
+export function policyWorkerFold(detail: TranscriptDetailPolicy, askedByModel: boolean): Fold {
+	if (detail.worker === "origin") return askedByModel ? "folded" : "expanded";
+	return detail.worker;
+}
+
+/** The override that flips a block away from its current effective state. */
+export function toggledFold(effective: Fold): Fold {
+	return effective === "expanded" ? "folded" : "expanded";
+}

package/src/tools/builtin-tool-catalog.ts

@@ -1,5 +1,6 @@
 import { type ToolName, ToolNames } from "../core/tool-names.js";
 import { OBSERVATION_POLICY_SLACK_BYTES, OBSERVE_SELF_CAPS } from "./observation.js";
+import { toolPresentationPolicy } from "./presentation.js";
 import { readMaxBytes } from "./read.js";
 import type { ToolMetadata, ToolSourceInfo, ToolSpec } from "./registry.js";
 
@@ -255,9 +256,14 @@ export function toolPromptHintsForNames(names: ReadonlyArray<ToolName>): Readonl
 	return hints;
 }
 
+// Every builtin carries its transcript presentation on its metadata, resolved
+// from the one declaration table in presentation.ts, so the registry and the
+// live panel (which has no registry) answer the fold question identically.
 function withBuiltinMetadata<T extends ToolSpec>(spec: T): T {
 	const metadata = TOOL_METADATA[spec.name];
-	return metadata ? withMetadata(spec, metadata) : spec;
+	return metadata
+		? withMetadata(spec, { ...metadata, presentation: toolPresentationPolicy(spec.name, undefined) })
+		: spec;
 }
 
 export function builtin<T extends ToolSpec>(spec: T, sourceInfo: ToolSourceInfo): T {

package/src/tools/presentation.ts

@@ -0,0 +1,107 @@
+/**
+ * Typed tool presentation policy. Answers, per tool, what the transcript's
+ * balanced (`/output default`) view needs to know: does the block open folded
+ * or expanded, does the folded row keep a mutation diff visible, and does a
+ * failed folded row carry an output excerpt.
+ *
+ * The panel must not decide any of that by tool name. It asks this module,
+ * which resolves the answer from two inputs: the registered presentation
+ * metadata for the tool (declared once here and attached to `ToolMetadata` by
+ * the builtin catalog) and the argument-sensitive resource-read rule. The
+ * lookup is a plain object read, so it stays cheap enough to call on every
+ * frame, and it needs no registry instance: the live chat panel has none.
+ *
+ * Pure module: no I/O, no registry construction, no UI imports.
+ */
+
+import { ToolNames } from "../core/tool-names.js";
+
+export type ToolFoldDefault = "expanded" | "folded";
+
+export interface ToolPresentationPolicy {
+	/** How a fresh block for this call renders before the operator touches it. */
+	foldDefault: ToolFoldDefault;
+	/**
+	 * Keep the mutation diff under the folded row. A folded `edit` that hides
+	 * what it changed tells the operator nothing they could act on; the diff is
+	 * the row's whole point and stays visible, bounded, until the body is opened.
+	 */
+	showDiffWhenFolded: boolean;
+	/**
+	 * Carry the last non-empty output line on a failed folded row. Bash pioneered
+	 * this so a failed command stays diagnosable without opening its body; every
+	 * tool that fails with text gets the same courtesy.
+	 */
+	failureExcerpt: boolean;
+}
+
+const FOLDED: ToolPresentationPolicy = { foldDefault: "folded", showDiffWhenFolded: false, failureExcerpt: true };
+const FOLDED_WITH_DIFF: ToolPresentationPolicy = {
+	foldDefault: "folded",
+	showDiffWhenFolded: true,
+	failureExcerpt: true,
+};
+
+/**
+ * Per-tool presentation declarations. Every builtin folds by default: a
+ * routine turn of six reads used to open six bodies, and the one-line row
+ * already carries the call, its outcome facts, size, and settlement. Mutations
+ * keep their diff under the folded row. Everything unlisted, including dynamic
+ * tools, folds the same way.
+ */
+export const TOOL_PRESENTATION: Readonly<Record<string, ToolPresentationPolicy>> = {
+	[ToolNames.Read]: FOLDED,
+	[ToolNames.Grep]: FOLDED,
+	[ToolNames.Find]: FOLDED,
+	[ToolNames.Ls]: FOLDED,
+	[ToolNames.CodeNav]: FOLDED,
+	[ToolNames.Context]: FOLDED,
+	[ToolNames.CredentialPresent]: FOLDED,
+	[ToolNames.Write]: FOLDED_WITH_DIFF,
+	[ToolNames.Edit]: FOLDED_WITH_DIFF,
+	[ToolNames.Bash]: FOLDED,
+	[ToolNames.Git]: FOLDED,
+	[ToolNames.Verify]: FOLDED,
+	[ToolNames.Dispatch]: FOLDED,
+	[ToolNames.Monitor]: FOLDED,
+	[ToolNames.Steer]: FOLDED,
+	[ToolNames.Tasks]: FOLDED,
+	[ToolNames.Ledger]: FOLDED,
+	[ToolNames.WebFetch]: FOLDED,
+	[ToolNames.AskUser]: FOLDED,
+	[ToolNames.Artifact]: FOLDED,
+};
+
+function readStringField(args: unknown, key: string): string | null {
+	if (typeof args !== "object" || args === null || Array.isArray(args)) return null;
+	const value = (args as Record<string, unknown>)[key];
+	return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+/**
+ * Compact resource-read classification. Reads of skill/handbook/agent
+ * instruction files and docs pages collapse to one labeled line and never
+ * auto-expand; their bodies are reference material, not task output.
+ */
+export function classifyResourceRead(toolName: string, args: unknown): string | null {
+	if (toolName !== ToolNames.Read) return null;
+	const path = readStringField(args, "path");
+	if (path === null) return null;
+	const normalized = path.replace(/\\/g, "/");
+	const base = normalized.split("/").pop() ?? "";
+	if (base === "SKILL.md") return "skill";
+	if (base === "CLIO-CODER.md") return "handbook";
+	if (base === "AGENTS.md") return "agents";
+	if (/(^|\/)docs\//.test(normalized)) return "docs";
+	return null;
+}
+
+/**
+ * Resolve the presentation policy for one call. Argument-sensitive rules win
+ * over the per-tool declaration because a resource read is a property of the
+ * path, not of the `read` tool.
+ */
+export function toolPresentationPolicy(toolName: string, args: unknown): ToolPresentationPolicy {
+	if (classifyResourceRead(toolName, args) !== null) return FOLDED;
+	return TOOL_PRESENTATION[toolName] ?? FOLDED;
+}

package/src/tools/registry.ts

@@ -26,6 +26,7 @@ import { hashToolCall } from "../domains/safety/loop-detector.js";
 import { detectValidationCommand } from "../domains/safety/protected-artifacts.js";
 import { askUserExposure } from "./ask-user.js";
 import { type DispatchPlanView, describeDispatchPlan } from "./dispatch-plan.js";
+import type { ToolPresentationPolicy } from "./presentation.js";
 import { shapeToolResult } from "./result-shaping.js";
 
 /**
@@ -76,6 +77,11 @@ export interface ToolMetadata {
 	 * need none; the schema description covers them.
 	 */
 	promptHint?: string;
+	/**
+	 * How transcript surfaces present this tool's block under `/output default`.
+	 * Optional: tools that declare nothing fold like every other tool.
+	 */
+	presentation?: ToolPresentationPolicy;
 }
 
 export interface ToolSpec {