@iowarp/clio-coder 0.3.6 → 0.3.7

package/src/interactive/interactive-application.ts

@@ -10,10 +10,12 @@ import type { DispatchContract } from "../domains/dispatch/contract.js";
 import type { ExtensionsContract } from "../domains/extensions/index.js";
 import type { InteropContract } from "../domains/interop/index.js";
 import type { TaskMemoryOperatorStatus } from "../domains/memory/index.js";
+import { openDetachedBatchViews } from "../domains/middleware/index.js";
 import type { ObservabilityContract } from "../domains/observability/index.js";
 import type { ProvidersContract, ThinkingLevel } from "../domains/providers/index.js";
 import type { ResourcesContract } from "../domains/resources/index.js";
 import type { FleetNodeSnapshot } from "../domains/scheduling/cluster.js";
+import type { SchedulingContract } from "../domains/scheduling/contract.js";
 import type { DecisionLedgerEntry } from "../domains/session/entries.js";
 import type { SessionContract, SessionEntry, TaskBoardSnapshot } from "../domains/session/index.js";
 import type { ShareContract } from "../domains/share/index.js";
@@ -26,8 +28,10 @@ import { APPLICATION_DOUBLE_TAP_MS, type ApplicationController } from "./applica
 import type { ChatLoop, ChatLoopEvent } from "./chat-loop.js";
 import { emitCommandNotice } from "./command-fallbacks.js";
 import { appendNotice } from "./command-output.js";
+import { dispatchCouncilThroughRegistry } from "./council-dispatch.js";
 import { createDispatchSteering } from "./dispatch-steering.js";
 import { createEditorSubmitController } from "./editor-submit.js";
+import { createInteractiveDesktopNotifications } from "./footer/notifications.js";
 import { createInteractiveEventProjection } from "./interactive-event-projection.js";
 import { createInteractiveInputRuntime } from "./interactive-input-runtime.js";
 import { createInteractivePresentation } from "./interactive-presentation.js";
@@ -108,6 +112,8 @@ export interface InteractiveDeps {
 	providers: ProvidersContract;
 	dispatch: DispatchContract;
 	agents?: AgentsContract;
+	/** Session budget state `/fleet run` shows as the ceiling a plan is admitted under. */
+	scheduling?: SchedulingContract;
 	observability: ObservabilityContract;
 	chat: ChatLoop;
 	/** Fired once after the first real TUI render transaction issued all of its terminal writes. */
@@ -541,6 +547,16 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 	} = presentation;
 	refreshPresentationFooter = () => footer.refresh();
 	const agentProgress = createAgentProgress(terminal);
+	// Desktop notifications are a protocol write on the terminal owner, issued
+	// outside any render transaction, so the sequence carries frameId null and
+	// never lands inside a frame. A non-TTY process never emits one even when
+	// `CLIO_CODER_INTERACTIVE=1` forced the interactive surface on.
+	const desktopNotifications = createInteractiveDesktopNotifications({
+		write: (data) => terminal.write(data),
+		enabled: () => deps.getSettings?.().terminal.notify ?? false,
+		interactiveTty: () => process.stdout.isTTY === true,
+		getOpenBatches: () => openDetachedBatchViews(deps.dispatch),
+	});
 	const busNoticeSink = {
 		appendReplayBlock: (renderBlock: Parameters<typeof chatPanel.appendReplayBlock>[0]) =>
 			chatRenderer.mutate(() => chatPanel.appendReplayBlock(renderBlock), "bus-notice"),
@@ -570,6 +586,7 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 		setLastTurnSummary: (summary) => presentation.setLastTurnSummary(summary),
 		startTerminalProgress: () => agentProgress.start(),
 		stopTerminalProgress: () => agentProgress.stop(),
+		onTurnEnded: () => desktopNotifications.turnEnded(),
 		refreshLiveWorkspaceGit,
 		refreshFooter: () => footer.refresh(),
 		requestRender: () => tui.requestRender(),
@@ -587,6 +604,10 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 	// The overlay reads the report this process already produced at boot; it
 	// never probes on a keystroke.
 	const interop = deps.interop;
+	// `/council` reaches execution only through the tool registry, so the
+	// approval overlay this application already installs on it is the same one an
+	// operator-typed council parks.
+	const toolRegistry = deps.toolRegistry;
 	const interopSurface = interop ? interopOverlaySurface(interop, (level, text) => notify(level, text)) : null;
 	const slashRuntime = createInteractiveSlashRuntime({
 		io,
@@ -626,8 +647,12 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 		readStructuredEntries,
 		expandSubmit: (text) => expandInteractiveSubmitAsync(text, deps.resources),
 		openAskUser: (questions, options) => openAskUserOverlayState(questions, options),
-		openSkillsHub: () => openSkillsHubState(),
+		openSkillsHub: (tab) => openSkillsHubState(tab),
 		openCost: () => openCostOverlayState(),
+		openSideQuestion: (question) => openSideQuestionOverlayState(question),
+		startHandoff: (goal) => startHandoffState(goal),
+		startFleetRun: (name, vars) => startFleetRunState(name, vars),
+		...(toolRegistry ? { runCouncilDispatch: (args) => dispatchCouncilThroughRegistry(toolRegistry, args) } : {}),
 		openContextView: () => openContextViewOverlayState(),
 		openTasks: () => openTasksOverlayState(),
 		openDecisions: () => openDecisionsOverlayState(),
@@ -705,6 +730,7 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 		notify,
 		terminal,
 		dispatchBoard,
+		setFleetRunPhase: (runId, phase) => dispatchBoardStore.setFleetPhase(runId, phase),
 		chatPanel,
 		resetTranscript,
 		io,
@@ -714,11 +740,26 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 		keybindings,
 		editor,
 		getSlashContext: () => slashRuntime.context,
+		// One terminal owner, so the external editor a handoff review opens gets
+		// the screen the same way the composer's own `$EDITOR` opener does.
+		suspendTerminal: (run) => {
+			try {
+				tui.stop();
+				return run();
+			} finally {
+				tui.start();
+				tui.requestRender(true);
+			}
+		},
+		onOperatorParked: () => desktopNotifications.approvalParked(),
 	});
 	const {
 		closeOverlay,
 		openAskUserOverlayState,
 		openCostOverlayState,
+		openSideQuestionOverlayState,
+		startHandoffState,
+		startFleetRunState,
 		openContextViewOverlayState,
 		openContextResetOverlayState,
 		openTasksOverlayState,
@@ -810,6 +851,7 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 		renderContextIsland: interactiveTickers.renderContextIsland,
 		requestRender: () => tui.requestRender(),
 		notify,
+		onDispatchSettled: () => desktopNotifications.dispatchSettled(),
 		// The reducer mutates one state object per assignment, so the panel is
 		// handed that object rather than a copy: a streamed delta reaches the
 		// screen by invalidating a cached render, not by rebuilding the entry.

package/src/interactive/interactive-event-projection.ts

@@ -77,6 +77,11 @@ export interface InteractiveEventProjectionDeps {
 	setLastTurnSummary: (summary: TurnSummary) => void;
 	startTerminalProgress: () => void;
 	stopTerminalProgress: () => void;
+	/**
+	 * One model turn reached its end. Wired to the desktop notification; absent
+	 * on hosts that do not own a terminal to notify through.
+	 */
+	onTurnEnded?: () => void;
 	refreshLiveWorkspaceGit: (force: boolean) => void;
 	refreshFooter: () => void;
 	requestRender: () => void;
@@ -214,7 +219,10 @@ export function createInteractiveEventProjection(deps: InteractiveEventProjectio
 		deps.chat.onEvent((event) => {
 			const showProgress = deps.getSettings?.().terminal.showTerminalProgress ?? false;
 			if (event.type === "agent_start" && showProgress) deps.startTerminalProgress();
-			else if (event.type === "agent_end") deps.stopTerminalProgress();
+			else if (event.type === "agent_end") {
+				deps.stopTerminalProgress();
+				deps.onTurnEnded?.();
+			}
 		}),
 		deps.bus.on(BusChannels.RunAborted, () => {
 			deps.stopTerminalProgress();

package/src/interactive/interactive-slash-runtime.ts

@@ -16,9 +16,12 @@ import {
 	type ThinkingLevel,
 	thinkingLevelChoiceLabel,
 } from "../domains/providers/index.js";
-import type { ResourcesContract } from "../domains/resources/index.js";
+import type { LibraryEntryKind, ResourcesContract } from "../domains/resources/index.js";
 import { installSkill } from "../domains/resources/skills/marketplace.js";
+import { foldDecisionBoard } from "../domains/session/decision-board.js";
 import type { SessionContract, SessionEntry } from "../domains/session/index.js";
+import { foldTaskBoard } from "../domains/session/task-board.js";
+import { filterEntriesToActivePath } from "../domains/session/tree/active-path.js";
 import type { ShareContract } from "../domains/share/index.js";
 import type { UserTasksStore } from "../domains/user-tasks/store.js";
 import { stripTerminalSequences } from "../engine/tui.js";
@@ -32,9 +35,11 @@ import { appendNotice, appendOperatorCommand } from "./command-output.js";
 import { runOperatorRecall } from "./context-recall-command.js";
 import { renderSessionHtml } from "./export-html/index.js";
 import { dateLocal } from "./format-time.js";
+import type { OracleDigestSources } from "./oracle.js";
 import type { SettingsCenterRowId, SettingsSectionId } from "./overlays/settings.js";
 import {
 	type ContextClearCommandOptions,
+	type CouncilDispatchOutcome,
 	dispatchSlashCommand,
 	type InitCommandOptions,
 	parseSlashCommand,
@@ -108,8 +113,21 @@ export interface InteractiveSlashRuntimeDeps {
 	session?: Pick<SessionContract, "tree" | "current" | "appendEntry">;
 	expandSubmit: (text: string) => Promise<InteractiveSlashSubmitExpansion>;
 	openAskUser: AskUserHandler;
-	openSkillsHub: () => void;
+	openSkillsHub: (tab?: LibraryEntryKind) => void;
 	openCost: () => void;
+	/** Run one `/btw` side question in its own overlay. */
+	openSideQuestion: (question: string) => void;
+	/** Run one `/handoff <goal>`: extract, review, and seed a successor session. */
+	startHandoff: (goal: string) => void;
+	/** Run one `/fleet run <name>`: approval preview first, dispatch only on accept. */
+	startFleetRun?: (name: string, vars: Readonly<Record<string, string>>) => void;
+	/**
+	 * Run one `/council <task>`: the prepared dispatch-tool arguments go through
+	 * the ordinary tool-admission path, so supervised autonomy parks the call and
+	 * the approval overlay opens before any member runs. Absent on a host with no
+	 * tool registry, in which case `/council` says so.
+	 */
+	runCouncilDispatch?: (args: Readonly<Record<string, unknown>>) => Promise<CouncilDispatchOutcome>;
 	openContextView: () => void;
 	openTasks: () => void;
 	openDecisions: () => void;
@@ -186,6 +204,29 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 	const resources = deps.resources;
 	const userTasks = deps.userTasks;
 
+	/**
+	 * The record `/oracle` briefs its advisor on. Entries are filtered to the
+	 * active branch first, the same way the task board, compaction, and the
+	 * finish contract read them (issue #94): after a `/tree` switch the raw file
+	 * still holds the abandoned turns, and an unscoped fold would brief the
+	 * advisor on decisions the operator walked away from.
+	 */
+	const oracleBriefingSources = (): Omit<OracleDigestSources, "question"> => {
+		const sessionId = deps.chat.getSessionId();
+		if (sessionId === null) return { decisions: [], tasks: [], compactionSummary: null };
+		const leafTurnId = deps.session?.tree(sessionId).leafId ?? undefined;
+		const entries = filterEntriesToActivePath(deps.readStructuredEntries(sessionId), leafTurnId);
+		let compactionSummary: string | null = null;
+		for (const entry of entries) {
+			if (entry.kind === "compactionSummary") compactionSummary = entry.summary;
+		}
+		return {
+			decisions: foldDecisionBoard(entries),
+			tasks: foldTaskBoard(entries)?.tasks ?? [],
+			compactionSummary,
+		};
+	};
+
 	const appendCommandNotice: SlashCommandContext["notice"] = (level, text) => {
 		appendNotice(level, text, {
 			appendReplayBlock: (renderBlock) => deps.chatPanel.appendReplayBlock(renderBlock),
@@ -342,6 +383,15 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 				: deps.share.importArchive(resolve(archivePath), importOptions);
 		},
 		openCost: deps.openCost,
+		openSideQuestion: deps.openSideQuestion,
+		// `/oracle` is refused, never queued, while a turn streams: the digest it
+		// packs describes the record as it stands.
+		isTurnInFlight: () => deps.chat.isStreaming(),
+		oracleBriefing: oracleBriefingSources,
+		startHandoff: deps.startHandoff,
+		...(deps.startFleetRun ? { startFleetRun: deps.startFleetRun } : {}),
+		...(deps.getSettings ? { getWorkerRosters: () => deps.getSettings?.().workers.rosters ?? {} } : {}),
+		...(deps.runCouncilDispatch ? { runCouncilDispatch: deps.runCouncilDispatch } : {}),
 		openContextView: deps.openContextView,
 		openTasks: deps.openTasks,
 		openDecisions: deps.openDecisions,

package/src/interactive/interactive-subscriptions.ts

@@ -37,6 +37,12 @@ export interface InteractiveSubscriptionsDeps {
 	recordWorkerRun?: (fields: WorkerRunEntryFields) => void;
 	/** Sealed-receipt reader, injected by tests. Defaults to `<state>/receipts/<runId>.json`. */
 	readWorkerReceipt?: WorkerReceiptReader;
+	/**
+	 * A dispatch run reached a terminal state. The desktop notification uses it
+	 * to look for a detached batch that settled with this run; nothing else
+	 * derives state from it.
+	 */
+	onDispatchSettled?: () => void;
 }
 
 export interface InteractiveSubscriptions {
@@ -89,8 +95,14 @@ export function createInteractiveSubscriptions(deps: InteractiveSubscriptionsDep
 			}),
 		),
 		deps.bus.on(BusChannels.RunAborted, folded(workers.aborted)),
-		deps.bus.on(BusChannels.DispatchCompleted, folded(workers.completed)),
-		deps.bus.on(BusChannels.DispatchFailed, folded(workers.failed)),
+		deps.bus.on(BusChannels.DispatchCompleted, (payload) => {
+			folded(workers.completed)(payload);
+			deps.onDispatchSettled?.();
+		}),
+		deps.bus.on(BusChannels.DispatchFailed, (payload) => {
+			folded(workers.failed)(payload);
+			deps.onDispatchSettled?.();
+		}),
 		deps.bus.on(BusChannels.ContextActivity, () => {
 			deps.refreshFooter();
 			deps.renderContextIsland();

package/src/interactive/oracle.ts

@@ -0,0 +1,179 @@
+/**
+ * `/oracle <question>`: the briefing an advisor is given, and the note its
+ * answer becomes.
+ *
+ * Oracle never receives a forked transcript. A transcript is the session's raw
+ * history, and handing it to an advisor makes the advisor agree with whatever
+ * the session already believes, which is the opposite of what an operator asks
+ * an oracle for. It is briefed on the record instead: the decisions the
+ * operator settled, the work the board still owes, and the last compaction
+ * summary when one exists.
+ *
+ * Pure: no I/O, no bus, no session, no dispatch. The caller owns the run.
+ */
+
+import type { OracleResult } from "../domains/agents/index.js";
+import type { DecisionLedgerEntry } from "../domains/session/entries.js";
+import type { TaskBoardTask } from "../domains/session/task-board.js";
+
+/** The recipe `/oracle` dispatches. Shadow, so `/run` can never reach it. */
+export const ORACLE_AGENT_ID = "oracle";
+
+/**
+ * Total bound on the packed briefing, in UTF-8 bytes. Well under the 64 KiB
+ * an internal-origin dispatch briefing may carry, because the point of the
+ * digest is that a small local advisor can hold all of it at once.
+ */
+export const ORACLE_DIGEST_MAX_BYTES = 12 * 1024;
+
+/**
+ * Per-section byte caps. They sum to 11776, which leaves 512 bytes of the
+ * total for the section headers and blank lines the packer writes between
+ * them. Each section is clamped on its own before the whole digest is clamped
+ * again, so one runaway section can never starve the others: a 40 KiB
+ * compaction summary loses its own tail rather than the question's.
+ */
+export const ORACLE_DECISIONS_MAX_BYTES = 5120;
+export const ORACLE_TASKS_MAX_BYTES = 3072;
+export const ORACLE_COMPACTION_MAX_BYTES = 2048;
+export const ORACLE_QUESTION_MAX_BYTES = 1536;
+
+/** Row caps, applied before the byte caps. Newest decisions and lowest task ids first. */
+export const ORACLE_DECISIONS_MAX_ROWS = 24;
+export const ORACLE_TASKS_MAX_ROWS = 24;
+
+/** Appended wherever a cap cut content, so the advisor knows it is reading a tail-less record. */
+export const ORACLE_TRUNCATION_MARKER = "\n[truncated]";
+
+export const ORACLE_NO_DECISIONS = "(no settled decisions on this branch)";
+export const ORACLE_NO_TASKS = "(no open tasks on the board)";
+
+export interface OracleDigestSources {
+	/** Settled interviews, newest first, exactly as the decision board folds them. */
+	decisions: ReadonlyArray<DecisionLedgerEntry>;
+	/** The live task board's tasks; the packer keeps the open ones. */
+	tasks: ReadonlyArray<TaskBoardTask>;
+	/** The most recent compaction summary on the active branch, or null when the session never compacted. */
+	compactionSummary: string | null;
+	question: string;
+}
+
+export interface OracleDigest {
+	text: string;
+	/** True when any cap cut content. The digest says so in its own text as well. */
+	truncated: boolean;
+}
+
+function byteLength(text: string): number {
+	return Buffer.byteLength(text, "utf8");
+}
+
+/**
+ * Clamp to `maxBytes` including the marker, never past a UTF-8 code point. A
+ * marker that pushed the result over its own cap would make the section caps
+ * unable to add up to the total, which is the one property the packer relies
+ * on.
+ */
+function clamp(text: string, maxBytes: number): { text: string; truncated: boolean } {
+	if (byteLength(text) <= maxBytes) return { text, truncated: false };
+	const room = Math.max(0, maxBytes - byteLength(ORACLE_TRUNCATION_MARKER));
+	const buffer = Buffer.from(text, "utf8");
+	let cut = Math.min(room, buffer.byteLength);
+	while (cut > 0) {
+		const next = buffer[cut];
+		if (next === undefined || (next & 0xc0) !== 0x80) break;
+		cut -= 1;
+	}
+	return { text: `${buffer.subarray(0, cut).toString("utf8")}${ORACLE_TRUNCATION_MARKER}`, truncated: true };
+}
+
+/** One decision line. Superseded decisions carry their correction so a reversal is visible. */
+function decisionLine(decision: DecisionLedgerEntry["decisions"][number]): string {
+	const label = decision.label ? ` (${decision.label})` : "";
+	if (decision.status === "superseded") {
+		const correction = decision.correction ? `; corrected to ${decision.correction}` : "";
+		return `- ${decision.key}${label}: ${decision.value} [superseded${correction}]`;
+	}
+	return `- ${decision.key}${label}: ${decision.value}`;
+}
+
+function taskLine(task: TaskBoardTask): string {
+	return `- ${task.id} [${task.status}] ${task.title}`;
+}
+
+function isOpenTask(task: TaskBoardTask): boolean {
+	return task.status === "pending" || task.status === "active";
+}
+
+/**
+ * Pack the briefing. Sections are fixed and always present, so an advisor
+ * reading an empty one learns that the board is empty rather than that the
+ * packer omitted it.
+ */
+export function packOracleDigest(sources: OracleDigestSources): OracleDigest {
+	let truncated = false;
+
+	const decisionRows = sources.decisions
+		.flatMap((entry) => entry.decisions.map(decisionLine))
+		.slice(0, ORACLE_DECISIONS_MAX_ROWS);
+	if (decisionRows.length < sources.decisions.reduce((total, entry) => total + entry.decisions.length, 0)) {
+		truncated = true;
+	}
+	const decisions = clamp(decisionRows.join("\n") || ORACLE_NO_DECISIONS, ORACLE_DECISIONS_MAX_BYTES);
+	truncated = truncated || decisions.truncated;
+
+	const openTasks = sources.tasks.filter(isOpenTask);
+	const taskRows = openTasks.map(taskLine).slice(0, ORACLE_TASKS_MAX_ROWS);
+	if (taskRows.length < openTasks.length) truncated = true;
+	const tasks = clamp(taskRows.join("\n") || ORACLE_NO_TASKS, ORACLE_TASKS_MAX_BYTES);
+	truncated = truncated || tasks.truncated;
+
+	const summaryText = sources.compactionSummary?.trim() ?? "";
+	const summary = clamp(summaryText, ORACLE_COMPACTION_MAX_BYTES);
+	truncated = truncated || summary.truncated;
+
+	const question = clamp(sources.question.trim(), ORACLE_QUESTION_MAX_BYTES);
+	truncated = truncated || question.truncated;
+
+	const sections = [
+		"## Settled decisions",
+		decisions.text,
+		"",
+		"## Open tasks",
+		tasks.text,
+		"",
+		"## Last compaction summary",
+		summary.text.length > 0 ? summary.text : "(this session has not compacted)",
+		"",
+		"## Question",
+		question.text,
+	];
+	const whole = clamp(sections.join("\n"), ORACLE_DIGEST_MAX_BYTES);
+	return { text: whole.text, truncated: truncated || whole.truncated };
+}
+
+/** The bounded task an oracle run is given. The briefing carries the record; this carries the job. */
+export const ORACLE_TASK =
+	"Answer the question in the briefing's Question section. Check it against the settled decisions first, " +
+	"then return the strongest challenge you can support and the evidence that would change your mind.";
+
+/**
+ * The advisor's structured answer as the prose the operator note carries. The
+ * contract keeps the four fields typed so a run cannot half-answer; the note
+ * renders them because the main agent reads prose, not a payload.
+ */
+export function formatOracleAnswer(result: OracleResult): string {
+	const cited =
+		result.citedDecisions.length === 0
+			? "Cited decisions: none bear on this question."
+			: `Cited decisions: ${result.citedDecisions.join(", ")}`;
+	return [
+		`Verdict: ${result.verdict}`,
+		"",
+		`Strongest challenge: ${result.challenge}`,
+		"",
+		`What would change its mind: ${result.changesMyMind}`,
+		"",
+		cited,
+	].join("\n");
+}

package/src/interactive/overlay-ask-user-lifecycle.ts

@@ -14,6 +14,11 @@ export interface OverlayAskUserLifecycleDeps {
 	requestRender(): void;
 	registerHandler?(handler: AskUserHandler): () => void;
 	openAskUserOverlay?: typeof openAskUserOverlay;
+	/**
+	 * An ask_user request parked waiting for the operator. Fired when the
+	 * overlay session opens, not per question, so one interview notifies once.
+	 */
+	onOperatorParked?(): void;
 }
 
 export interface OverlayAskUserLifecycle {
@@ -61,6 +66,7 @@ export function createOverlayAskUserLifecycle(deps: OverlayAskUserLifecycleDeps)
 		deps.setOverlayState("ask-user");
 		session = openSession(deps.tui, { onCancel: () => pendingCancel?.() });
 		deps.setOverlayHandle(session);
+		deps.onOperatorParked?.();
 		deps.requestRender();
 		return session;
 	};