@iowarp/clio-coder 0.3.9 → 0.4.0

package/src/core/bus-events.ts

@@ -468,6 +468,8 @@ export interface PermissionRequestedPayload {
 	/** Sanitized one-line preview of the call's object (command, path, or compact args). */
 	target?: string | undefined;
 	timeoutMs?: number | undefined;
+	/** Admitted timeout fallback, so the operator surface can name what an expired ask became. */
+	fallback?: "deny" | "fail" | undefined;
 	escalation?: boolean | undefined;
 }
 
@@ -486,6 +488,8 @@ export interface PermissionResolvedPayload {
 	actionClass?: string | undefined;
 	reason?: string | undefined;
 	requestedBy?: string | undefined;
+	/** Effective fallback applied to an expired worker escalation. */
+	fallback?: "deny" | "fail" | undefined;
 	at?: number | undefined;
 }
 

package/src/core/config.ts

@@ -1010,6 +1010,7 @@ const TOP_LEVEL_KEYS = [
 	"compaction",
 	"context",
 	"prewarm",
+	"panes",
 	"retry",
 	"guardrails",
 ] as const;
@@ -1607,6 +1608,54 @@ export function validateSettings(raw: unknown): SettingsValidationResult {
 		}
 	}
 
+	if ("panes" in raw) {
+		if (!isPlainObject(raw.panes)) {
+			issues.add("panes", `expected a map, got ${describe(raw.panes)}`);
+		} else {
+			// `agents` and `keepFailed` are retired: pane-opening is no longer a
+			// per-dispatch policy (src/interactive/pane-policy.ts holds the one
+			// decision). They stay accepted-and-ignored so a settings file written
+			// against an older release keeps passing the strict boot gate.
+			issues.unknownKeys("panes", raw.panes, ["enabled", "agents", "keepFailed", "notifications", "journal", "yazi"]);
+			if ("enabled" in raw.panes) {
+				const v = expectEnum(issues, "panes.enabled", raw.panes.enabled, ["auto", "embedded", "off"] as const);
+				if (v !== undefined) settings.panes.enabled = v;
+			}
+			if ("notifications" in raw.panes) {
+				const v = expectEnum(issues, "panes.notifications", raw.panes.notifications, ["failures", "all", "off"] as const);
+				if (v !== undefined) settings.panes.notifications = v;
+			}
+			if ("journal" in raw.panes) {
+				const v = expectBoolean(issues, "panes.journal", raw.panes.journal);
+				if (v !== undefined) settings.panes.journal = v;
+			}
+			if ("yazi" in raw.panes) {
+				if (!isPlainObject(raw.panes.yazi)) {
+					issues.add("panes.yazi", `expected a map, got ${describe(raw.panes.yazi)}`);
+				} else {
+					const yazi = raw.panes.yazi;
+					issues.unknownKeys("panes.yazi", yazi, ["enabled", "mode", "profile", "followCwd"]);
+					if ("enabled" in yazi) {
+						const v = expectBoolean(issues, "panes.yazi.enabled", yazi.enabled);
+						if (v !== undefined) settings.panes.yazi.enabled = v;
+					}
+					if ("mode" in yazi) {
+						const v = expectEnum(issues, "panes.yazi.mode", yazi.mode, ["companion", "chooser"] as const);
+						if (v !== undefined) settings.panes.yazi.mode = v;
+					}
+					if ("profile" in yazi) {
+						const v = expectEnum(issues, "panes.yazi.profile", yazi.profile, ["managed", "user"] as const);
+						if (v !== undefined) settings.panes.yazi.profile = v;
+					}
+					if ("followCwd" in yazi) {
+						const v = expectBoolean(issues, "panes.yazi.followCwd", yazi.followCwd);
+						if (v !== undefined) settings.panes.yazi.followCwd = v;
+					}
+				}
+			}
+		}
+	}
+
 	if ("retry" in raw) {
 		if (!isPlainObject(raw.retry)) {
 			issues.add("retry", `expected a map, got ${describe(raw.retry)}`);

package/src/core/defaults.ts

@@ -1,3 +1,5 @@
+// Default constants for Clio Coder settings.
+
 /**
  * Default settings shipped with Clio Coder. Written to the resolved config
  * directory's settings.yaml on first install if the file does not already
@@ -166,6 +168,34 @@ export interface PrewarmSettings {
 	enabled: boolean;
 }
 
+/**
+ * The pane layer's settings block.
+ *
+ * `journal` is the durable half: the run event journal, which every other pane
+ * surface reads and which the standalone run viewer needs whether or not a pane
+ * host is installed. The run-view settings govern the live projection. The
+ * Yazi chooser remains useful without a pane host because it can borrow the
+ * terminal for one selection.
+ */
+export interface PanesSettings {
+	/**
+	 * Capability rung the pane layer may reach. `auto` takes guest mode when a
+	 * pane host is detected; `embedded` asks Clio to own a private session, which
+	 * degrades to none until that ships; `off` skips detection entirely.
+	 */
+	enabled: "auto" | "embedded" | "off";
+	/** Which terminal run states raise a pane-host toast. */
+	notifications: "failures" | "all" | "off";
+	journal: boolean;
+	/** File-pane round-trip settings read live for each explicit open. */
+	yazi: {
+		enabled: boolean;
+		mode: "companion" | "chooser";
+		profile: "managed" | "user";
+		followCwd: boolean;
+	};
+}
+
 /**
  * Transient provider retry controls for the interactive chat loop. These are
  * intentionally small and mirror the session retry helper defaults. Dispatched
@@ -368,16 +398,20 @@ export const DEFAULT_SETTINGS = {
 			enabled: true,
 			everyNTools: 10,
 			windowSteps: 8,
-			maxTokens: 400,
+			// Budget for the answer and any reasoning tokens that precede it.
+			// An always-on-thinking 35B spent the measured 400/400 completion
+			// tokens on reasoning and stopped with finish_reason=length before it
+			// emitted content, so the old budget made a useful step unreachable.
+			maxTokens: 2000,
 			// A memory step runs detached from the turn that triggered it, but it
 			// runs on a real inference endpoint that the operator's own turns and
 			// dispatched workers also queue against. The operator's ledger over 14
 			// days recorded 60 llm-tier steps spending 1,666 seconds of model time
 			// for 6 injections, with one step holding a local server for 102.5
-			// seconds to answer nothing. The deadline is what a turn boundary can
-			// actually wait for; a step that runs past it is recorded as timed out
-			// rather than spending the remaining minutes unobserved.
-			timeoutMs: 30_000,
+			// seconds to answer nothing. A viable output budget earns one minute,
+			// while consecutive timeouts degrade the plane to its free rules tier
+			// instead of repeatedly occupying the endpoint for that full minute.
+			timeoutMs: 60_000,
 		},
 	},
 	watchdog: { enabled: false } as WatchdogSettings,
@@ -466,6 +500,32 @@ export const DEFAULT_SETTINGS = {
 	prewarm: {
 		enabled: true,
 	} as PrewarmSettings,
+	panes: {
+		/**
+		 * Off: a plain `clio-coder` performs zero pane-host work, and none of the
+		 * mux domain even loads. The extension is activated per session with
+		 * `clio-coder --with-panes`, or durably by setting this to `auto` (guest
+		 * mode when a pane host is detected). The flag beats the setting in both
+		 * directions.
+		 */
+		enabled: "off",
+		/** A toast per finished run is noise; a toast per failure is the signal. */
+		notifications: "failures",
+		/**
+		 * Tee every dispatched run's display event tail to
+		 * `<state>/runs/<runId>/events.ndjson`. The live tail is otherwise
+		 * in-process only, so this is what lets `clio-coder fleet view` follow a
+		 * run from a second terminal. Written regardless of any pane host being
+		 * present; turning it off costs the viewer its transcript and nothing else.
+		 */
+		journal: true,
+		yazi: {
+			enabled: true,
+			mode: "companion",
+			profile: "managed",
+			followCwd: true,
+		},
+	} as PanesSettings,
 	retry: {
 		enabled: true,
 		maxRetries: 3,
@@ -560,8 +620,10 @@ memory:
     enabled: true
     everyNTools: 10
     windowSteps: 8
-    maxTokens: 400
-    timeoutMs: 30000
+    # Covers the answer and any thinking before it. An always-on-thinking 35B
+    # spent the measured 400/400 tokens on reasoning, then stopped at length.
+    maxTokens: 2000
+    timeoutMs: 60000
 
 # Opt-in turn-end watchdog. When enabled, a turn that changed the tree is
 # reviewed by one read-only verifier run briefed with the turn's coalesced diff
@@ -781,6 +843,30 @@ context:
 prewarm:
   enabled: true
 
+# The pane layer. Off by default: plain \`clio-coder\` does no pane-host work at
+# all. Start \`clio-coder --with-panes\` to activate the extension for one
+# session, or set enabled: auto to activate it whenever a pane host is
+# detected (embedded, a Clio-owned private session, is not implemented yet).
+# The command-line flag beats this setting in both directions. notifications
+# picks which terminal run states raise a toast. journal tees every dispatched
+# run's event tail to <state>/runs/<runId>/events.ndjson so
+# \`clio-coder fleet view <runId> --follow\` can watch a run from a second
+# terminal; it is written regardless of any pane host being present. Journal
+# directories are removed when their run leaves the run ledger ring, and
+# \`clio-coder reset --state\` clears them with the rest of the state root.
+panes:
+  enabled: off
+  notifications: failures
+  journal: true
+  # The files pane uses a managed, reproducible Yazi profile by default.
+  # profile: user preserves the operator's Yazi configuration and therefore
+  # forces one-shot chooser mode, since that profile has no Clio pick chord.
+  yazi:
+    enabled: true
+    mode: companion
+    profile: managed
+    followCwd: true
+
 # Transient provider/stream retry controls for interactive chat.
 # Retryable errors include overloads, rate limits, 5xx responses, network
 # resets, and timeouts. Context overflow uses compaction recovery instead.

package/src/core/response-schema.ts

@@ -21,6 +21,28 @@ export const RESPONSE_SCHEMA_RUNTIME_ID = "llamacpp";
 /** The runtime that takes the standard OpenAI `json_schema` response format. */
 export const OPENAI_SCHEMA_RUNTIME_ID = "lmstudio";
 
+/**
+ * The LiteLLM gateway, which takes the same standard `json_schema` format.
+ *
+ * This is the one gateway admitted to the table above, and it is admitted on
+ * measurement rather than on the api family the warning describes. Against a
+ * LiteLLM v1.98.0 proxy fronting both a llama.cpp and an LM Studio upstream:
+ * `{"type":"json_schema", json_schema:{...}}` was grammar-enforced end to end
+ * through both, `{"type":"json_object", schema:{...}}` was enforced through
+ * llama.cpp but rejected HTTP 400 by LM Studio, and the same prompt with no
+ * `response_format` returned plain prose. LiteLLM's `drop_params` did not strip
+ * either spelling, because `response_format` is a parameter it recognizes and
+ * forwards whole.
+ *
+ * The standard dialect is therefore the only one that holds across every
+ * upstream a gateway may route to, which is why LiteLLM belongs with LM Studio
+ * here and not with llama.cpp. Re-verify with the gateway's own smoke test
+ * before trusting this against a proxy other than LiteLLM: the hazard the
+ * warning names is real, and the only thing that makes this entry safe is that
+ * somebody measured it.
+ */
+export const GATEWAY_SCHEMA_RUNTIME_ID = "litellm";
+
 /**
  * How a runtime spells a JSON-schema response constraint on the wire.
  *
@@ -47,14 +69,32 @@ export type ResponseSchemaDialect = "llamacpp-json-object" | "openai-json-schema
 export function responseSchemaDialectFor(runtimeId: string): ResponseSchemaDialect | null {
 	if (runtimeId === RESPONSE_SCHEMA_RUNTIME_ID) return "llamacpp-json-object";
 	if (runtimeId === OPENAI_SCHEMA_RUNTIME_ID) return "openai-json-schema";
+	if (runtimeId === GATEWAY_SCHEMA_RUNTIME_ID) return "openai-json-schema";
 	return null;
 }
 
-/** Whether this runtime speaks the dialect above. Transport shape, not capability. */
+/**
+ * Whether this runtime speaks the dialect above. Transport shape, not capability.
+ *
+ * LiteLLM joins llama.cpp here because a gateway in front of llama.cpp is the
+ * same transport with one hop added, and the hop was measured not to alter it.
+ * That is what admits a contract-bearing worker to a gateway target; without
+ * it, every typed agent behind a proxy is refused rather than enforced.
+ *
+ * It also opts LiteLLM into {@link responseSchemaConflictsWithTools}, which is
+ * deliberately conservative. Whether a schema and a tool surface can constrain
+ * the same completion is a property of the upstream, and one alias may route to
+ * llama.cpp (which refuses both with HTTP 400) while another routes to LM Studio
+ * (which accepts them). A runtime id cannot tell those apart, so this treats
+ * every gateway upstream as if it were the refusing one. The cost is a
+ * tool-bearing contract run through an LM Studio upstream falling back to the
+ * prompt parser when it did not strictly have to. The alternative is paying a
+ * round trip to discover a predictable 400, and having the answer depend on
+ * which deployment the proxy happened to pick for that request.
+ */
 export function runtimeSpeaksResponseSchemaDialect(runtime: { id: string; kind: string; apiFamily: string }): boolean {
-	return (
-		runtime.id === RESPONSE_SCHEMA_RUNTIME_ID && runtime.kind === "http" && runtime.apiFamily === "openai-completions"
-	);
+	if (runtime.kind !== "http" || runtime.apiFamily !== "openai-completions") return false;
+	return runtime.id === RESPONSE_SCHEMA_RUNTIME_ID || runtime.id === GATEWAY_SCHEMA_RUNTIME_ID;
 }
 
 /**

package/src/core/theme-token-hex.ts

@@ -0,0 +1,43 @@
+/** Semantic colors shared by Clio's terminal surfaces and generated companion profiles. */
+export type ClioToken =
+	| "accent"
+	| "accentDeep"
+	| "action"
+	| "success"
+	| "warning"
+	| "error"
+	| "info"
+	| "reason"
+	| "dim"
+	| "muted"
+	| "title"
+	| "frame"
+	| "frameStrong";
+
+/**
+ * The palette's lowercase hex projection.
+ *
+ * Keep this leaf free of interactive imports. Generated companion profiles
+ * need the color vocabulary without becoming a second reacher of the terminal
+ * renderer and splitting the instant shell's Stage 0 chunk.
+ */
+const TOKEN_HEX: Readonly<Record<ClioToken, `#${string}`>> = {
+	accent: "#46e5d0",
+	accentDeep: "#1fb7a6",
+	action: "#ff7e29",
+	success: "#57e389",
+	warning: "#ffb454",
+	error: "#ff5c66",
+	info: "#5ba8ff",
+	reason: "#9d8cff",
+	dim: "#6a7a85",
+	muted: "#8a99a4",
+	title: "#46e5d0",
+	frame: "#2f5d5a",
+	frameStrong: "#2aab9e",
+};
+
+/** The canonical lowercase `#rrggbb` value for one Clio theme token. */
+export function tokenHex(token: ClioToken): `#${string}` {
+	return TOKEN_HEX[token];
+}

package/src/core/tool-names.ts

@@ -7,7 +7,7 @@
  *   OBSERVE      read, grep, find, ls, code_nav, context, credential_present
  *   MUTATE       write, edit
  *   EXECUTE      bash, git, verify
- *   ORCHESTRATE  dispatch, monitor, steer, tasks
+ *   ORCHESTRATE  dispatch, monitor, steer, tasks, panes
  *   RETRIEVE     web_fetch
  *   INTERACT     ask_user
  *   ARTIFACT     artifact
@@ -35,6 +35,7 @@ export const ToolNames = {
 	Steer: "steer",
 	Tasks: "tasks",
 	Ledger: "ledger",
+	Panes: "panes",
 	// RETRIEVE
 	WebFetch: "web_fetch",
 	// INTERACT

package/src/core/xdg.ts

@@ -20,7 +20,7 @@ import { join } from "node:path";
  *
  * Role contents: config holds user-authored files (settings, credentials,
  * agents, skills, prompts, extensions, runtimes); data holds durable artifacts
- * (memory, evidence, evals); state holds machine-produced session state
+ * (memory, evidence, evals, vendored tools); state holds machine-produced session state
  * (sessions, audit, receipts, runs.json, recent-models.json, install.json,
  * interviews, scratch); cache holds disposable derived files.
  */

package/src/domains/agents/fleets/build-review.md

@@ -29,6 +29,3 @@ task above. Nothing you write here persuades it.
 
 If it fails you, you receive its failed checks as input data and get exactly one
 revision. Close the findings it reported and nothing else.
-
-Answer with your `mutation-report`. Include `commitMessage`: one imperative
-subject line describing this change, as you would write it in the log.

package/src/domains/agents/fleets/build-test.md

@@ -30,6 +30,3 @@ If the suite comes back red you will receive its output as input data. Repair
 exactly what it reported. Do not restate the failure, do not weaken or delete a
 test to make it pass, and do not widen the change beyond the repair. You get at
 most two repair attempts before the run fails with the suite still red.
-
-Answer with your `mutation-report`. Include `commitMessage`: one imperative
-subject line describing this change, as you would write it in the log.

package/src/domains/agents/result-contract-filesystem.ts

@@ -0,0 +1,32 @@
+/**
+ * The one live-disk implementation of `ResultContractFilesystem`.
+ *
+ * `result-contract.ts` takes filesystem access as an argument so the validators
+ * stay deterministic and testable without touching a disk. That leaves every
+ * caller to supply the same three accessors, and the worker and the
+ * orchestrator had each written their own copy. A capability added to the
+ * interface then lands in one of them and not the other, which is how a Scout
+ * citation could ground inside the worker's repair rounds and fail the
+ * orchestrator's sealed revalidation of the identical result. One factory, both
+ * callers, no drift.
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import type { ResultContractFilesystem } from "./result-contract.js";
+
+export function nodeResultContractFilesystem(): ResultContractFilesystem {
+	return {
+		readFile(filePath) {
+			try {
+				return readFileSync(filePath, "utf8");
+			} catch {
+				return null;
+			}
+		},
+		pathExists(filePath) {
+			return existsSync(filePath);
+		},
+		isDirectory(filePath) {
+			return statSync(filePath, { throwIfNoEntry: false })?.isDirectory() === true;
+		},
+	};
+}