@iowarp/clio-coder 0.3.6 → 0.3.7

package/src/interactive/cost-overlay.ts

@@ -32,6 +32,10 @@ export interface CostRow {
 	cacheWrite: number;
 	reasoningTokens: number;
 	apiCalls: number;
+	/** Calls in this row that were `/btw` side questions rather than turns. */
+	sideQuestions: number;
+	/** Calls in this row that were `/handoff` extraction rounds rather than turns. */
+	handoffs: number;
 	cost: CostAggregate;
 }
 
@@ -61,6 +65,8 @@ export function aggregateCostEntries(entries: ReadonlyArray<CostEntry>): CostRow
 			existing.row.cacheWrite += entry.cacheWrite;
 			existing.row.reasoningTokens += entry.reasoningTokens;
 			existing.row.apiCalls += entry.apiCalls ?? 1;
+			if (entry.label === "side-question") existing.row.sideQuestions += 1;
+			if (entry.label === "handoff") existing.row.handoffs += 1;
 			for (const requestedModelId of entry.requestedModelIds) existing.requestedModelIds.add(requestedModelId);
 			addResponseModelIdObservationCounts(
 				existing.responseModelIdObservationCounts,
@@ -81,6 +87,8 @@ export function aggregateCostEntries(entries: ReadonlyArray<CostEntry>): CostRow
 				cacheWrite: entry.cacheWrite,
 				reasoningTokens: entry.reasoningTokens,
 				apiCalls: entry.apiCalls ?? 1,
+				sideQuestions: entry.label === "side-question" ? 1 : 0,
+				handoffs: entry.label === "handoff" ? 1 : 0,
 			},
 			requestedModelIds: new Set(entry.requestedModelIds),
 			responseModelIdObservationCounts: { ...entry.responseModelIdObservationCounts },
@@ -117,8 +125,21 @@ function sumRows(
 			cacheWrite: acc.cacheWrite + row.cacheWrite,
 			reasoningTokens: acc.reasoningTokens + row.reasoningTokens,
 			apiCalls: acc.apiCalls + row.apiCalls,
+			sideQuestions: acc.sideQuestions + row.sideQuestions,
+			handoffs: acc.handoffs + row.handoffs,
 		}),
-		{ runs: 0, tokens: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, reasoningTokens: 0, apiCalls: 0 },
+		{
+			runs: 0,
+			tokens: 0,
+			input: 0,
+			output: 0,
+			cacheRead: 0,
+			cacheWrite: 0,
+			reasoningTokens: 0,
+			apiCalls: 0,
+			sideQuestions: 0,
+			handoffs: 0,
+		},
 	);
 }
 
@@ -166,9 +187,14 @@ function summaryBlock(totalCost: CostAggregate, totalTokens: number, rows: Reado
 	// unknown` it printed for a target that reports no pricing. The token rows
 	// below are measured and stay either way. See formatCostAggregate.
 	const cost = formatCostAggregate(totalCost);
+	// A side question is billed like anything else and is counted here, but it is
+	// deliberately not a turn: it never entered the session, so `turns` above
+	// excludes it and this row says how much of the spend sat beside the session.
 	return kvBlock([
-		["turns", formatTokens(totals.runs)],
+		["turns", formatTokens(totals.runs - totals.sideQuestions - totals.handoffs)],
 		["model calls", formatTokens(totals.apiCalls)],
+		...(totals.sideQuestions > 0 ? [["side questions", formatTokens(totals.sideQuestions)] as const] : []),
+		...(totals.handoffs > 0 ? [["handoffs", formatTokens(totals.handoffs)] as const] : []),
 		...(cost === null ? [] : [["cost", cost] as const]),
 		["input", formatTokens(totals.input)],
 		["output", formatTokens(totals.output)],
@@ -187,8 +213,10 @@ function modelBlock(row: CostRow): string[] {
 	return kvBlock([
 		["requested model ids", row.requestedModelIds.join(", ")],
 		["response model id observation", responseModelIdObservationCountsLabel(row.responseModelIdObservationCounts)],
-		["turns", formatTokens(row.runs)],
+		["turns", formatTokens(row.runs - row.sideQuestions - row.handoffs)],
 		["model calls", formatTokens(row.apiCalls)],
+		...(row.sideQuestions > 0 ? [["side questions", formatTokens(row.sideQuestions)] as const] : []),
+		...(row.handoffs > 0 ? [["handoffs", formatTokens(row.handoffs)] as const] : []),
 		...(cost === null ? [] : [["cost", cost] as const]),
 		["input", formatTokens(row.input)],
 		["output", formatTokens(row.output)],

package/src/interactive/council-dispatch.ts

@@ -0,0 +1,30 @@
+/**
+ * The one path `/council` takes into execution: the dispatch tool, admitted by
+ * the ordinary tool registry.
+ *
+ * The registry is where classification, safety, autonomy, middleware, and the
+ * operator approval park all live. A council started from the composer is a
+ * plan-scale dispatch exactly as a council the model asks for is, so it is
+ * admitted the same way and parks the same approval overlay. Nothing here
+ * builds a request, resolves a route, or touches the dispatch domain.
+ */
+
+import { ToolNames } from "../core/tool-names.js";
+import type { ToolRegistry } from "../tools/registry.js";
+import type { CouncilDispatchOutcome } from "./slash-commands.js";
+
+/**
+ * Invoke the dispatch tool with prepared council arguments and report the
+ * verdict in the command's own vocabulary. A tool that is not visible in this
+ * posture and a call the operator declined are both reported as what they are,
+ * because a council that never ran must never read as one that did.
+ */
+export async function dispatchCouncilThroughRegistry(
+	registry: Pick<ToolRegistry, "invoke">,
+	args: Readonly<Record<string, unknown>>,
+): Promise<CouncilDispatchOutcome> {
+	const verdict = await registry.invoke({ tool: ToolNames.Dispatch, args: { ...args } });
+	if (verdict.kind === "blocked") return { status: "blocked", reason: verdict.reason };
+	if (verdict.kind === "not_visible") return { status: "error", message: verdict.reason };
+	return verdict.result.kind === "error" ? { status: "error", message: verdict.result.message } : { status: "ok" };
+}

package/src/interactive/council-grid.ts

@@ -0,0 +1,213 @@
+/**
+ * How a council reads on the Fleet Runs board.
+ *
+ * A council is one question asked of several members at once, so its runs are
+ * one thing on the screen rather than three to five unrelated cards. Members
+ * sit side by side while every column keeps enough width to read an answer in,
+ * and stack one under another when they do not. The synthesis run is the whole
+ * council's answer, so it takes the full width under the members rather than a
+ * column of its own.
+ *
+ * Pure presentation: the caller projects board rows into these views, and this
+ * module owns only layout, color, and text. It knows nothing about the board
+ * store, the bus, or run status semantics.
+ */
+
+import { truncateToWidth, wrapTextWithAnsi } from "../engine/tui.js";
+import {
+	type ClioTheme,
+	type ClioToken,
+	dotSep,
+	GLYPH,
+	innerDivider,
+	isClioToken,
+	padAnsi,
+	paintHex,
+} from "./theme/index.js";
+
+/**
+ * The narrowest column an answer is still worth reading in. Below it the grid
+ * becomes a set of one-word columns, so the group stacks instead: a member's
+ * answer is the reason the operator opened the board.
+ */
+export const COUNCIL_COLUMN_MIN_WIDTH = 34;
+
+/** Blank columns between two side-by-side member columns. */
+export const COUNCIL_COLUMN_GUTTER = 2;
+
+/** Rows of a member's bounded answer tail a column shows before it defers to `/view`. */
+export const COUNCIL_ANSWER_ROWS = 4;
+
+/** The label the coordinator gives the synthesis run of every council group. */
+export const COUNCIL_SYNTHESIS_LABEL = "synthesis";
+
+/** One council run as the board draws it: the roster facts plus the run's presentation. */
+export interface CouncilMemberView {
+	runId: string;
+	label: string;
+	/** Roster color: a theme token name or a `#rrggbb` value. Absent members take the accent. */
+	color?: string;
+	round: number;
+	/** Route as the card names it, such as `local/example-model`. */
+	route: string;
+	status: { glyph: string; label: string; token: ClioToken };
+	/** Bounded answer tail the board already keeps for this run. */
+	tailText: string;
+	droppedLines: number;
+}
+
+export interface CouncilGroupView {
+	group: string;
+	/** Final-round member runs, in roster order. */
+	members: ReadonlyArray<CouncilMemberView>;
+	/** The council's own answer, or null while the members are still running. */
+	synthesis: CouncilMemberView | null;
+	/** Aggregate status of the group, used by the compact card. */
+	status: { glyph: string; label: string; token: ClioToken };
+	/** Highest round any member has reached. */
+	round: number;
+	/** Elapsed time of the longest-running member, formatted by the caller. */
+	elapsed: string;
+	/** Run id of the selected row when the selection sits inside this group. */
+	selectedRunId?: string;
+}
+
+export type CouncilLayout = { mode: "grid"; columnWidth: number } | { mode: "stack"; columnWidth: number };
+
+/**
+ * Grid or stack for this many members at this content width. Columns divide the
+ * width evenly after the gutters are taken out, and the whole group stacks the
+ * moment one column would fall under {@link COUNCIL_COLUMN_MIN_WIDTH}: a grid
+ * where only some columns are readable is worse than no grid at all.
+ */
+export function councilGridLayout(memberCount: number, contentWidth: number): CouncilLayout {
+	const count = Math.max(1, memberCount);
+	const usable = contentWidth - COUNCIL_COLUMN_GUTTER * (count - 1);
+	const columnWidth = Math.floor(usable / count);
+	if (count > 1 && columnWidth >= COUNCIL_COLUMN_MIN_WIDTH) return { mode: "grid", columnWidth };
+	return { mode: "stack", columnWidth: Math.max(1, contentWidth) };
+}
+
+/**
+ * A member's label in its roster color. A theme token name is painted as that
+ * token; a `#rrggbb` value is painted literally; anything else, including a
+ * member with no color at all, takes the accent, which is what the board paints
+ * the operator's own work in.
+ */
+function councilLabelText(theme: ClioTheme, label: string, color?: string): string {
+	if (color !== undefined && isClioToken(color)) return theme.style(color, label, { bold: true });
+	if (color !== undefined) {
+		const painted = paintHex(label, color);
+		if (painted !== label) return painted;
+	}
+	return theme.style("accent", label, { bold: true });
+}
+
+/** The answer tail on a rail, wrapped to the column and bounded to {@link COUNCIL_ANSWER_ROWS} rows. */
+function answerRows(theme: ClioTheme, member: CouncilMemberView, width: number, maxRows: number): string[] {
+	if (member.tailText.trim().length === 0) return [];
+	const railWidth = Math.max(1, width - 2);
+	const wrapped: string[] = [];
+	for (const line of member.tailText.split("\n")) {
+		for (const row of wrapTextWithAnsi(line, railWidth)) wrapped.push(row);
+	}
+	const shown = wrapped.slice(Math.max(0, wrapped.length - maxRows));
+	const hidden = wrapped.length - shown.length + member.droppedLines;
+	const rail = theme.fg("dim", `${GLYPH.rail} `);
+	const rows = shown.map((row) => `${rail}${theme.fg("muted", row)}`);
+	if (hidden > 0) {
+		rows.push(`${rail}${theme.fg("dim", truncateToWidth(`${hidden} more`, railWidth, "…", false))}`);
+	}
+	return rows;
+}
+
+/**
+ * One member column: the label, the route, the round and status, then the
+ * answer. Every line is clipped to the column so a long model id or a long
+ * answer line can never push a neighbouring column out of position.
+ */
+export function councilMemberLines(
+	theme: ClioTheme,
+	member: CouncilMemberView,
+	width: number,
+	options: { selected?: boolean; maxAnswerRows?: number } = {},
+): string[] {
+	const dot = dotSep(theme);
+	const cursor = options.selected === true ? `${theme.fg("accent", GLYPH.cursor)} ` : "";
+	const status = theme.fg(member.status.token, `${member.status.glyph} ${member.status.label}`);
+	const head = `${cursor}${councilLabelText(theme, member.label, member.color)}`;
+	const lines = [
+		truncateToWidth(head, width, "…", false),
+		truncateToWidth(theme.fg("muted", member.route), width, "…", false),
+		truncateToWidth(`${status}${dot}${theme.fg("dim", `r${member.round}`)}`, width, "…", false),
+		...answerRows(theme, member, width, options.maxAnswerRows ?? COUNCIL_ANSWER_ROWS),
+	];
+	return lines.map((line) => padAnsi(line, width));
+}
+
+/** Zip member columns into rows, padding short columns so the grid keeps its shape. */
+function zipColumns(columns: ReadonlyArray<ReadonlyArray<string>>, columnWidth: number): string[] {
+	const height = columns.reduce((tallest, column) => Math.max(tallest, column.length), 0);
+	const gutter = " ".repeat(COUNCIL_COLUMN_GUTTER);
+	const rows: string[] = [];
+	for (let index = 0; index < height; index += 1) {
+		rows.push(columns.map((column) => column[index] ?? " ".repeat(columnWidth)).join(gutter));
+	}
+	return rows;
+}
+
+/**
+ * The council group's body: the member grid or stack, then the synthesis run
+ * full width under it. The caller frames the result.
+ */
+export function councilGroupBody(theme: ClioTheme, group: CouncilGroupView, contentWidth: number): string[] {
+	const layout = councilGridLayout(group.members.length, contentWidth);
+	const body: string[] = [];
+	if (layout.mode === "grid") {
+		const columns = group.members.map((member) =>
+			councilMemberLines(theme, member, layout.columnWidth, {
+				selected: member.runId === group.selectedRunId,
+			}),
+		);
+		body.push(...zipColumns(columns, layout.columnWidth));
+	} else {
+		for (const member of group.members) {
+			if (body.length > 0) body.push(innerDivider(theme, contentWidth));
+			body.push(
+				...councilMemberLines(theme, member, layout.columnWidth, {
+					selected: member.runId === group.selectedRunId,
+				}),
+			);
+		}
+	}
+	if (group.synthesis !== null) {
+		body.push(innerDivider(theme, contentWidth));
+		body.push(
+			...councilMemberLines(theme, group.synthesis, contentWidth, {
+				selected: group.synthesis.runId === group.selectedRunId,
+				maxAnswerRows: COUNCIL_ANSWER_ROWS + 2,
+			}),
+		);
+	}
+	return body;
+}
+
+/**
+ * The compact Fleet Runs island card for a council: one row for the whole
+ * group, naming how many members are seated and which round they are on. The
+ * grid belongs to the expanded board, where there is width to read it in.
+ */
+export function councilIslandLines(theme: ClioTheme, group: CouncilGroupView, width: number): string[] {
+	const dot = dotSep(theme);
+	const glyph = theme.fg(group.status.token, group.status.glyph);
+	const status = theme.fg(group.status.token, group.status.label);
+	const title = theme.paint(`council ${group.group}`, { bold: true });
+	const head = `${glyph} ${title}${dot}${status}${dot}${theme.fg("muted", group.elapsed)}`;
+	const seats = `${group.members.length} member${group.members.length === 1 ? "" : "s"}`;
+	const facts = [
+		theme.fg("muted", seats),
+		theme.fg("dim", `r${group.round}`),
+		...(group.synthesis !== null ? [theme.fg("info", COUNCIL_SYNTHESIS_LABEL)] : []),
+	].join(dot);
+	return [padAnsi(truncateToWidth(head, width, "…", false), width), padAnsi(`  ${facts}`, width)];
+}

package/src/interactive/council.ts

@@ -0,0 +1,99 @@
+/**
+ * `/council [--roster <name>] [--rounds <n>] [--synthesis judge|vote|none] <task>`:
+ * the roster an operator-typed council resolves to and the dispatch-tool
+ * arguments it becomes.
+ *
+ * The command owns no execution path of its own. It shapes the same arguments
+ * a model would pass to the dispatch tool and hands them to the tool registry,
+ * so admission, the approval overlay under supervised autonomy, receipts, and
+ * the Fleet Runs board treat an operator council exactly as they treat one the
+ * model asked for.
+ *
+ * Pure: no I/O, no bus, no session, no dispatch. The caller owns the run.
+ */
+
+/**
+ * The roster `--roster` falls back to. It is an ordinary roster name, so an
+ * operator declares it the same way they declare any other one, and a project
+ * with no roster called `default` gets the refusal rather than a guess.
+ */
+export const COUNCIL_DEFAULT_ROSTER = "default";
+
+/** Synthesis modes the dispatch tool declares, in the order the usage line lists them. */
+export const COUNCIL_SYNTHESIS_MODES = ["judge", "vote", "none"] as const;
+export type CouncilSynthesisMode = (typeof COUNCIL_SYNTHESIS_MODES)[number];
+
+/** Rounds the dispatch tool admits. The command enforces the same bound where the operator typed it. */
+export const COUNCIL_MAX_ROUNDS = 3;
+
+export function isCouncilSynthesisMode(value: string): value is CouncilSynthesisMode {
+	return COUNCIL_SYNTHESIS_MODES.some((mode) => mode === value);
+}
+
+/** What the command needs to know about a configured roster: that it exists and how many members it seats. */
+export interface CouncilRosterFacts {
+	members: ReadonlyArray<unknown>;
+}
+
+export type CouncilRosters = Readonly<Record<string, CouncilRosterFacts>>;
+
+export interface CouncilCommandOptions {
+	roster?: string;
+	rounds?: number;
+	synthesis?: CouncilSynthesisMode;
+}
+
+export type CouncilRosterResolution = { ok: true; roster: string } | { ok: false; reason: string };
+
+/**
+ * The notice a session with no roster and no `--roster` gets. It names the
+ * setting rather than the failure, because an operator who types `/council`
+ * without a roster has not made a mistake. They have not declared one yet.
+ */
+export const COUNCIL_NO_ROSTER_NOTICE =
+	`/council needs a roster. Declare one under workers.rosters in settings.yaml, for example ` +
+	`workers.rosters.${COUNCIL_DEFAULT_ROSTER} with two to five members, each with a label and a target, ` +
+	`then run /council <task> or name another roster with --roster <name>.`;
+
+function knownRosterNames(rosters: CouncilRosters): string[] {
+	return Object.keys(rosters).sort();
+}
+
+/**
+ * Which roster this council runs. A named roster must exist; an unnamed one
+ * resolves to `workers.rosters.default` when that roster exists. Neither is
+ * guessed from the roster list: seating a council from whichever roster happens
+ * to be first would run models the operator never chose.
+ */
+export function resolveCouncilRoster(requested: string | undefined, rosters: CouncilRosters): CouncilRosterResolution {
+	const known = knownRosterNames(rosters);
+	const wanted = requested?.trim();
+	if (wanted !== undefined && wanted.length > 0) {
+		if (Object.hasOwn(rosters, wanted)) return { ok: true, roster: wanted };
+		const names = known.length === 0 ? "none are configured" : `configured rosters: ${known.join(", ")}`;
+		return { ok: false, reason: `no roster named "${wanted}" in workers.rosters (${names})` };
+	}
+	if (Object.hasOwn(rosters, COUNCIL_DEFAULT_ROSTER)) return { ok: true, roster: COUNCIL_DEFAULT_ROSTER };
+	return { ok: false, reason: COUNCIL_NO_ROSTER_NOTICE };
+}
+
+/**
+ * The dispatch-tool arguments this council becomes. Field names and value
+ * domains are the tool's own (`mode`, `roster`, `rounds`, `synthesis`), so the
+ * command adds no second grammar for the same contract. Defaults are left out
+ * rather than restated: the tool declares `rounds` 1 and `synthesis` none, and
+ * a caller that repeats them only creates a second place for them to drift.
+ */
+export function buildCouncilDispatchArgs(
+	task: string,
+	roster: string,
+	options: CouncilCommandOptions = {},
+): Record<string, unknown> {
+	return {
+		mode: "council",
+		task,
+		roster,
+		...(options.rounds !== undefined ? { rounds: options.rounds } : {}),
+		...(options.synthesis !== undefined ? { synthesis: options.synthesis } : {}),
+	};
+}