@iowarp/clio-coder 0.3.8 → 0.4.0

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
@@ -151,6 +153,49 @@ export interface WorkingSetSettings {
 	minEvictableTokens: number;
 }
 
+/**
+ * Prompt pre-warm settings (`prewarm`). On a local server prefill is the cost,
+ * and the prefix the next turn will send is fully known before the operator
+ * types anything: at session start, after a resume rebuilds the message array,
+ * and after a compaction settles. Clio sends that prefix to the backend right
+ * then so the slot's prefix cache already holds it when the real turn arrives.
+ *
+ *   - enabled: master switch. The feature is off on every tier but
+ *     `local-native` whatever this says, and off for workers and headless runs,
+ *     because it buys latency for an operator watching a local server.
+ */
+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
@@ -353,12 +398,20 @@ export const DEFAULT_SETTINGS = {
 			enabled: true,
 			everyNTools: 10,
 			windowSteps: 8,
-			maxTokens: 400,
-			// A memory step runs detached from the turn that triggered it, so a
-			// generous deadline costs no interactive latency. Measured steps on a
-			// small local route ranged past two minutes, and a deadline shorter than
-			// the model discards finished work as a timeout.
-			timeoutMs: 180_000,
+			// 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. 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,
@@ -444,6 +497,35 @@ export const DEFAULT_SETTINGS = {
 	context: {
 		workingSet: DEFAULT_WORKING_SET_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,
@@ -538,8 +620,10 @@ memory:
     enabled: true
     everyNTools: 10
     windowSteps: 8
-    maxTokens: 400
-    timeoutMs: 180000
+    # 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
@@ -751,6 +835,38 @@ context:
     protectLastTurns: 6
     minEvictableTokens: 200
 
+# Prompt pre-warm. At session start, after a resume rebuilds the message array,
+# and after a compaction settles, Clio sends the prefix the next turn would send
+# (minus your text) so a local server has already prefilled it when you press
+# Enter. Local-native targets only, interactive sessions only, and never while a
+# turn or a dispatch is running.
+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/endpoint-key.ts

@@ -0,0 +1,27 @@
+/**
+ * Canonical identity of an OpenAI-compatible inference endpoint: normalized
+ * HTTP scheme, lower-cased host, normalized port, and normalized base path with
+ * a conventional terminal `/v1` mount stripped. Credentials, query, and
+ * fragment do not participate. Host aliases are not resolved, so
+ * `localhost` and `127.0.0.1` stay distinct. Shared by dispatch capacity and
+ * residency locking so both speak the same key for one server.
+ */
+export function canonicalEndpointUrl(raw: string | null | undefined): string | null {
+	if (!raw?.trim()) return null;
+	try {
+		const url = new URL(raw.trim().replace(/^ws:/u, "http:").replace(/^wss:/u, "https:"));
+		url.protocol = url.protocol.toLowerCase();
+		if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+		url.hostname = url.hostname.toLowerCase();
+		url.username = "";
+		url.password = "";
+		url.hash = "";
+		url.search = "";
+		let path = url.pathname.replace(/\/{2,}/gu, "/").replace(/\/$/u, "");
+		if (path.endsWith("/v1")) path = path.slice(0, -3);
+		url.pathname = path || "/";
+		return url.toString().replace(/\/$/u, "");
+	} catch {
+		return null;
+	}
+}

package/src/core/residency-target-key.ts

@@ -0,0 +1,25 @@
+import { canonicalEndpointUrl } from "./endpoint-key.js";
+
+/** Runtime families whose model residency Clio can actively mutate. */
+export type ResidencyRuntimeId = "llamacpp" | "lmstudio" | "ollama-native";
+
+const RESIDENCY_RUNTIME_IDS: ReadonlySet<string> = new Set<ResidencyRuntimeId>([
+	"llamacpp",
+	"lmstudio",
+	"ollama-native",
+]);
+
+export function residencyTargetKey(runtimeId: ResidencyRuntimeId, baseUrl: string): string;
+export function residencyTargetKey(runtimeId: string, baseUrl: string | null | undefined): string | null;
+/** Stable key for one residency-managed server endpoint: its canonical URL. */
+export function residencyTargetKey(runtimeId: string, baseUrl: string | null | undefined): string | null {
+	if (!RESIDENCY_RUNTIME_IDS.has(runtimeId) || typeof baseUrl !== "string") return null;
+	// The key is the canonical endpoint itself, without a runtime prefix, so the
+	// residency lock and dispatch capacity name one server the same way (#250).
+	// A base url the canonical form refuses, such as one written without a
+	// scheme, still gets a key: callers store this in `ResidencyAdapter.targetKey`,
+	// which is a `string`, and dispatch capacity has no key for that target
+	// either, so there is nothing to agree with and nothing to gain by dropping
+	// the lock the reconciler serializes on.
+	return canonicalEndpointUrl(baseUrl) ?? baseUrl;
+}

package/src/core/response-schema.ts

@@ -11,16 +11,90 @@ export const RESPONSE_SCHEMA_MAX_SERIALIZED_BYTES = 64 * 1024;
  * `schema` key, and returns HTTP 200 with unconstrained JSON, so widening this
  * to the api family would convert a clean refusal into a silent
  * non-enforcement. lmstudio declares `structuredOutputs: "json-schema"`
- * truthfully and is still excluded here, because Clio has no dialect for its
- * transport. Widen this only together with a dialect for the runtime added.
+ * truthfully and is still excluded here, because the worker seam has no
+ * dialect for its transport. Widen this only together with a dialect for the
+ * runtime added; {@link responseSchemaDialectFor} is where the out-of-turn
+ * seam did exactly that (issue #223).
  */
 export const RESPONSE_SCHEMA_RUNTIME_ID = "llamacpp";
 
-/** Whether this runtime speaks the dialect above. Transport shape, not capability. */
+/** 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.
+ *
+ * `llamacpp-json-object` is llama-server's own `response_format: { type:
+ * "json_object", schema }`, which it compiles into a sampler grammar.
+ * `openai-json-schema` is the standard `response_format: { type:
+ * "json_schema", json_schema: { name, strict, schema } }` that LM Studio
+ * implements.
+ */
+export type ResponseSchemaDialect = "llamacpp-json-object" | "openai-json-schema";
+
+/**
+ * The dialect this runtime takes, or null when Clio has none for it and the
+ * request has to go unconstrained.
+ *
+ * Deliberately a name check, for the reason {@link RESPONSE_SCHEMA_RUNTIME_ID}
+ * gives: a generic OpenAI-compatible gateway answers HTTP 200 to a spelling it
+ * does not implement and returns unconstrained JSON, so a capability flag would
+ * turn a known non-enforcement into a silent one. This is the out-of-turn
+ * seam's table; the worker seam keeps the narrower
+ * {@link runtimeSpeaksResponseSchemaDialect} check, because a worker that
+ * cannot enforce a contract must refuse admission rather than degrade.
+ */
+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.
+ *
+ * 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;
+		},
+	};
+}