@iowarp/clio-coder 0.3.8 → 0.3.9

package/src/domains/observability/trace-store.ts

@@ -7,7 +7,7 @@
  */
 
 import { createHash } from "node:crypto";
-import { mkdirSync } from "node:fs";
+import { mkdirSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import { hostname } from "node:os";
 import { dirname, join } from "node:path";
@@ -27,6 +27,32 @@ export const TRACE_DATABASE_FILE = "trace.sqlite";
 export const TRACE_EVENT_POLL_LIMIT = 500;
 export const TRACE_PAYLOAD_LIMIT_BYTES = 16 * 1024;
 export const TRACE_WRITE_QUEUE_LIMIT = 2048;
+export const TRACE_RETENTION_DAYS_ENV = "CLIO_CODER_TRACE_RETENTION_DAYS";
+export const TRACE_MAX_BYTES_ENV = "CLIO_CODER_TRACE_MAX_BYTES";
+
+export interface TraceRetentionPolicy {
+	maxAgeDays: number;
+	maxBytes: number;
+}
+
+export interface TracePruneResult {
+	runsRemoved: number;
+	rowsRemoved: number;
+	bytesBefore: number;
+	bytesAfter: number;
+	bytesRemoved: number;
+	vacuumed: boolean;
+	protectedRuns: number;
+}
+
+/** Thirty days or 128 MiB, whichever limit the mirror reaches first. */
+export const DEFAULT_TRACE_RETENTION_POLICY: Readonly<TraceRetentionPolicy> = Object.freeze({
+	maxAgeDays: 30,
+	maxBytes: 128 * 1024 * 1024,
+});
+
+const MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1000;
+const VACUUM_RECLAIMABLE_FRACTION = 0.2;
 
 type DatabaseSyncConstructor = typeof import("node:sqlite").DatabaseSync;
 let sqliteConstructor: DatabaseSyncConstructor | null = null;
@@ -110,6 +136,40 @@ export function traceDatabasePath(stateDir: string): string {
 	return join(stateDir, TRACE_DATABASE_FILE);
 }
 
+/** Resolve the two operator-configurable retention bounds. */
+export function resolveTraceRetentionPolicy(
+	overrides: Partial<TraceRetentionPolicy> = {},
+	environment: NodeJS.ProcessEnv = process.env,
+): TraceRetentionPolicy {
+	const maxAgeDays =
+		overrides.maxAgeDays ??
+		parsePositiveRetentionNumber(environment[TRACE_RETENTION_DAYS_ENV], TRACE_RETENTION_DAYS_ENV, 1);
+	const maxBytes =
+		overrides.maxBytes ??
+		parsePositiveRetentionNumber(environment[TRACE_MAX_BYTES_ENV], TRACE_MAX_BYTES_ENV, 1024 * 1024);
+	return {
+		maxAgeDays: requirePositiveRetentionNumber(maxAgeDays, TRACE_RETENTION_DAYS_ENV, 1),
+		maxBytes: requirePositiveRetentionNumber(maxBytes, TRACE_MAX_BYTES_ENV, 1024 * 1024),
+	};
+}
+
+function parsePositiveRetentionNumber(raw: string | undefined, name: string, fallback: number): number {
+	if (raw === undefined || raw.trim().length === 0) {
+		return name === TRACE_RETENTION_DAYS_ENV
+			? DEFAULT_TRACE_RETENTION_POLICY.maxAgeDays
+			: DEFAULT_TRACE_RETENTION_POLICY.maxBytes;
+	}
+	const value = Number(raw);
+	return requirePositiveRetentionNumber(value, name, fallback);
+}
+
+function requirePositiveRetentionNumber(value: number, name: string, minimum: number): number {
+	if (!Number.isSafeInteger(value) || value < minimum) {
+		throw new Error(`${name} must be an integer of at least ${minimum}`);
+	}
+	return value;
+}
+
 export class TraceSchemaVersionError extends Error {
 	constructor(readonly found: number | null) {
 		super(
@@ -494,8 +554,13 @@ function reconcileAbandonedRuns(db: DatabaseSync): void {
 
 export class TraceStore {
 	readonly db: DatabaseSync;
+	private readonly retention: TraceRetentionPolicy;
 
-	constructor(readonly path: string) {
+	constructor(
+		readonly path: string,
+		options: { retention?: Partial<TraceRetentionPolicy> } = {},
+	) {
+		this.retention = resolveTraceRetentionPolicy(options.retention);
 		mkdirSync(dirname(path), { recursive: true });
 		this.db = new (databaseSyncConstructor())(path);
 		applyConnectionPragmas(this.db);
@@ -523,6 +588,86 @@ export class TraceStore {
 		}
 	}
 
+	/**
+	 * Remove whole terminal runs, including all of their dependent rows.
+	 *
+	 * Age pruning runs first. If the allocated database is still above the byte
+	 * limit, the oldest remaining terminal runs are removed until the live page
+	 * set fits or only queued/running runs remain. A live run is never a candidate.
+	 */
+	prune(policy: Partial<TraceRetentionPolicy> = this.retention, now = new Date().toISOString()): TracePruneResult {
+		const resolved = resolveTraceRetentionPolicy(policy);
+		const nowMs = Date.parse(now);
+		if (!Number.isFinite(nowMs)) throw new Error(`trace prune time is invalid: ${now}`);
+		const bytesBefore = traceDatabaseFootprintBytes(this.path);
+		let rowsRemoved = 0;
+		let runsRemoved = 0;
+		const removed = new Set<string>();
+		const cutoff = new Date(Math.max(0, nowMs - resolved.maxAgeDays * MILLISECONDS_PER_DAY)).toISOString();
+
+		const ageCandidates = this.db
+			.prepare(
+				"SELECT run_id FROM runs WHERE status IN ('success','fail') AND ended_at IS NOT NULL AND ended_at < ? ORDER BY ended_at, started_at, run_id",
+			)
+			.all(cutoff) as { run_id: string }[];
+		if (ageCandidates.length > 0) {
+			this.transaction(() => {
+				for (const candidate of ageCandidates) {
+					rowsRemoved += deleteTraceRun(this.db, candidate.run_id);
+					runsRemoved += 1;
+					removed.add(candidate.run_id);
+				}
+			});
+		}
+
+		let pages = tracePageStats(this.db);
+		if (pages.usedBytes > resolved.maxBytes) {
+			const sizeCandidates = this.db
+				.prepare(
+					"SELECT run_id FROM runs WHERE status IN ('success','fail') AND ended_at IS NOT NULL ORDER BY ended_at, started_at, run_id",
+				)
+				.all() as { run_id: string }[];
+			this.transaction(() => {
+				for (const candidate of sizeCandidates) {
+					if (pages.usedBytes <= resolved.maxBytes) break;
+					if (removed.has(candidate.run_id)) continue;
+					rowsRemoved += deleteTraceRun(this.db, candidate.run_id);
+					runsRemoved += 1;
+					removed.add(candidate.run_id);
+					pages = tracePageStats(this.db);
+				}
+			});
+		}
+
+		pages = tracePageStats(this.db);
+		const reclaimableFraction = pages.pageCount === 0 ? 0 : pages.freePages / pages.pageCount;
+		const sizeNeedsReclaim = pages.allocatedBytes > resolved.maxBytes && pages.freePages > 0;
+		const vacuumed =
+			rowsRemoved > 0 && pages.freePages > 0 && (reclaimableFraction >= VACUUM_RECLAIMABLE_FRACTION || sizeNeedsReclaim);
+		if (vacuumed) {
+			this.db.exec("VACUUM");
+			this.db.prepare("PRAGMA wal_checkpoint(TRUNCATE)").get();
+		}
+
+		const protectedRuns = Number(
+			(
+				this.db.prepare("SELECT COUNT(*) AS count FROM runs WHERE status IN ('queued','running')").get() as {
+					count: number | bigint;
+				}
+			).count,
+		);
+		const bytesAfter = traceDatabaseFootprintBytes(this.path);
+		return {
+			runsRemoved,
+			rowsRemoved,
+			bytesBefore,
+			bytesAfter,
+			bytesRemoved: Math.max(0, bytesBefore - bytesAfter),
+			vacuumed,
+			protectedRuns,
+		};
+	}
+
 	upsertRun(input: DispatchEnqueuedPayload, at = new Date().toISOString()): void {
 		this.transaction(() => {
 			this.db
@@ -859,6 +1004,7 @@ export class TraceStore {
 				startedAt: at,
 			});
 		});
+		this.prune(this.retention, at);
 	}
 
 	/**
@@ -971,7 +1117,51 @@ export class TraceStore {
 				startedAt: input.at,
 			});
 		});
+		this.prune(this.retention, input.at);
+	}
+}
+
+interface TracePageStats {
+	pageCount: number;
+	freePages: number;
+	allocatedBytes: number;
+	usedBytes: number;
+}
+
+function tracePageStats(db: DatabaseSync): TracePageStats {
+	const pageSize = Number((db.prepare("PRAGMA page_size").get() as { page_size: number | bigint }).page_size);
+	const pageCount = Number((db.prepare("PRAGMA page_count").get() as { page_count: number | bigint }).page_count);
+	const freePages = Number(
+		(db.prepare("PRAGMA freelist_count").get() as { freelist_count: number | bigint }).freelist_count,
+	);
+	return {
+		pageCount,
+		freePages,
+		allocatedBytes: pageCount * pageSize,
+		usedBytes: Math.max(0, pageCount - freePages) * pageSize,
+	};
+}
+
+function deleteTraceRun(db: DatabaseSync, runId: string): number {
+	let rows = 0;
+	for (const table of ["events", "envelopes", "gate_results", "agent_sessions", "processes", "phases", "runs"]) {
+		const result = db.prepare(`DELETE FROM ${table} WHERE run_id=?`).run(runId);
+		rows += Number(result.changes);
+	}
+	return rows;
+}
+
+function traceDatabaseFootprintBytes(path: string): number {
+	let total = 0;
+	for (const candidate of [path, `${path}-wal`, `${path}-shm`]) {
+		try {
+			total += statSync(candidate).size;
+		} catch (error) {
+			const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : "";
+			if (code !== "ENOENT") throw error;
+		}
 	}
+	return total;
 }
 
 export class TraceReader {

package/src/domains/prompts/compiler.ts

@@ -48,12 +48,22 @@ export interface SessionPromptInputs {
 	memorySection?: string;
 }
 
+/**
+ * Which section order `compile()` lays down. `volatility` is the product
+ * order; `legacy-0.3.8` reproduces the order shipped before issue #249 and
+ * exists so a test can prove the change is a pure permutation. Nothing in
+ * `src/` may pass `legacy-0.3.8`; the boundary is the test suite.
+ */
+export type SessionPromptSectionOrder = "volatility" | "legacy-0.3.8";
+
 export interface CompileInputs {
 	identity: string;
 	operatingContract: string;
 	safety: string;
 	sessionInputs: SessionPromptInputs;
 	additionalFragments?: ReadonlyArray<RenderedPromptFragment>;
+	/** Test-only escape hatch; see `SessionPromptSectionOrder`. Defaults to `volatility`. */
+	sectionOrder?: SessionPromptSectionOrder;
 }
 
 /** Stable inputs for one mediated fleet worker's canonical system prompt. */
@@ -439,21 +449,93 @@ function renderProjectBlock(contextFiles: string | undefined): string {
 	return trimmedFiles.length === 0 ? "" : `# Project\n\n${trimmedFiles}`;
 }
 
-function renderMemoryBlock(memorySection: string | undefined): string {
+/**
+ * The rendered memory section already opens with its own `# Memory` heading
+ * (`domains/memory/prompt-section.ts`), so prepending one unconditionally put
+ * the header in the prompt twice. Callers that pass a bare body still get a
+ * header; callers that pass a rendered section keep the one they wrote.
+ *
+ * `legacyDuplicateHeader` reproduces the 0.3.8 behavior and is reachable only
+ * through `sectionOrder: "legacy-0.3.8"`, so the permutation test compares
+ * against the whole prompt 0.3.8 emitted rather than a half-corrected one.
+ */
+function renderMemoryBlock(memorySection: string | undefined, legacyDuplicateHeader = false): string {
 	const trimmed = memorySection?.trim() ?? "";
-	return trimmed.length === 0 ? "" : `# Memory\n\n${trimmed}`;
+	if (trimmed.length === 0) return "";
+	if (legacyDuplicateHeader) return `# Memory\n\n${trimmed}`;
+	return /^#\s+Memory\s*$/.test(trimmed.split("\n", 1)[0] ?? "") ? trimmed : `# Memory\n\n${trimmed}`;
 }
 
 function estimatePromptTokens(text: string): number {
 	return ceilChars(text.trim().length);
 }
 
+/**
+ * The session prompt's section order, stable prefix first (issue #249).
+ *
+ * The rule, and it is the only rule: a section goes as late as its
+ * volatility, and anything that reads a clock, a probe, or a mutable store
+ * goes after everything that does not. Every backend Clio targets caches by
+ * exact prefix and re-prefills from the earliest changed byte, so a section
+ * that can change between two turns must not sit ahead of sections that
+ * cannot. That is why `runtime` is last of the compiled sections: its
+ * `Context window: N` moves when the backend reloads a model or a
+ * co-residency clamp lands, and before this order a single changed digit
+ * re-prefilled the tool contract, the roster, the hints, memory, and the
+ * project context behind it. `memory` sits just ahead of it because an
+ * approved memory record rewrites that section mid-session, and
+ * `project-context` is stable for the session's lifetime.
+ *
+ * The tail fragments (`workspace-root`, `clio-repo-awareness`,
+ * `project-rules`, `operator-profile`) are appended after this list in their
+ * own order: path-scoped project rules grow mid-session by design, which is
+ * exactly why they belong at the very end.
+ *
+ * Moving an entry here is a deliberate cache decision. `tests/contracts/
+ * prompt-prefix-layout.test.ts` pins this list so the move has to be made on
+ * purpose.
+ */
+export const SESSION_PROMPT_SECTION_ORDER: ReadonlyArray<string> = [
+	"identity",
+	"operating-contract",
+	"delegation",
+	"skills",
+	"safety",
+	"tool-contract",
+	"fleet",
+	"retrieval-hints",
+	"project-context",
+	"memory",
+	"runtime",
+];
+
+/**
+ * The order shipped through 0.3.8, kept only so a test can prove the new order
+ * is a permutation of it rather than a rewrite. Never reachable from `src/`.
+ */
+export const LEGACY_SESSION_PROMPT_SECTION_ORDER: ReadonlyArray<string> = [
+	"identity",
+	"operating-contract",
+	"delegation",
+	"skills",
+	"safety",
+	"runtime",
+	"tool-contract",
+	"fleet",
+	"retrieval-hints",
+	"memory",
+	"project-context",
+];
+
 /**
  * Compile the session system prompt. Identity and the operating contract
  * render verbatim from disk fragments; safety renders a one-line directive
  * plus the safety fragment body; everything else renders inline from typed
  * SessionPromptInputs. Output is one string, one sha256, one token estimate,
  * and a flat section breakdown for the /context overlay.
+ *
+ * Sections are laid down in `SESSION_PROMPT_SECTION_ORDER`, whose doc comment
+ * states the volatility rule that fixes it.
  */
 export function compile(table: FragmentTable, inputs: CompileInputs): CompiledSessionPrompt {
 	const identity = lookupFragment(table, inputs.identity, "identity");
@@ -493,17 +575,22 @@ export function compile(table: FragmentTable, inputs: CompileInputs): CompiledSe
 	const delegation = sessionCanDispatch(session) ? table.byId.get("operating.delegation") : undefined;
 	const skills = sessionHasContext(session) ? table.byId.get("operating.skills") : undefined;
 
-	push("identity", identityBody);
-	push("operating-contract", operatingContract.body);
-	if (delegation) push("delegation", delegation.body);
-	if (skills) push("skills", skills.body);
-	push("safety", renderSafetySection(safety, autonomyLevel));
-	push("runtime", renderRuntimeBlock(session));
-	push("tool-contract", renderToolContractBlock(session));
-	push("fleet", renderFleetBlock(session));
-	push("retrieval-hints", renderRetrievalHintsBlock(session));
-	push("memory", renderMemoryBlock(session.memorySection));
-	push("project-context", renderProjectBlock(session.contextFiles));
+	const legacy = inputs.sectionOrder === "legacy-0.3.8";
+	const rendered = new Map<string, string>([
+		["identity", identityBody],
+		["operating-contract", operatingContract.body],
+		["delegation", delegation?.body ?? ""],
+		["skills", skills?.body ?? ""],
+		["safety", renderSafetySection(safety, autonomyLevel)],
+		["runtime", renderRuntimeBlock(session)],
+		["tool-contract", renderToolContractBlock(session)],
+		["fleet", renderFleetBlock(session)],
+		["retrieval-hints", renderRetrievalHintsBlock(session)],
+		["memory", renderMemoryBlock(session.memorySection, legacy)],
+		["project-context", renderProjectBlock(session.contextFiles)],
+	]);
+	const order = legacy ? LEGACY_SESSION_PROMPT_SECTION_ORDER : SESSION_PROMPT_SECTION_ORDER;
+	for (const id of order) push(id, rendered.get(id) ?? "");
 	for (const fragment of inputs.additionalFragments ?? []) {
 		push(fragment.id, fragment.body);
 	}

package/src/domains/providers/endpoint-capacity.ts

@@ -0,0 +1,96 @@
+import { canonicalEndpointUrl } from "../../core/endpoint-key.js";
+import type { TargetStatus } from "./contract.js";
+import type { TargetDescriptor } from "./types/target-descriptor.js";
+
+export type EndpointCapacitySource = "override" | "discovered" | "local-native-default";
+
+export interface EndpointCapacity {
+	key: string;
+	label: string;
+	limit: number;
+	source: EndpointCapacitySource;
+}
+
+/** Runtime ids whose request schedulers are intentionally not modeled as fixed local slots. */
+const UNBOUNDED_LOCAL_NATIVE_RUNTIMES = new Set(["vllm", "sglang"]);
+
+/**
+ * Canonical identity of the inference scheduler behind a configured target.
+ * Scheme, normalized host and port, and normalized base path participate. DNS
+ * aliases do not collapse because Clio cannot prove they reach the same server.
+ */
+export function canonicalEndpointKey(value: TargetDescriptor | string): string | null {
+	return canonicalEndpointUrl(typeof value === "string" ? value : value.url);
+}
+
+/** Compact operator-facing identity. A non-root base path remains visible. */
+export function endpointLabel(endpointKey: string): string {
+	try {
+		const url = new URL(endpointKey);
+		return `${url.host}${url.pathname === "/" ? "" : url.pathname}`;
+	} catch {
+		return endpointKey;
+	}
+}
+
+function positiveInteger(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+
+/** Resolve the endpoint bound from configuration, cached discovery, or the local-native fallback. */
+export function endpointCapacityForStatus(status: TargetStatus): EndpointCapacity | null {
+	const key = canonicalEndpointKey(status.target);
+	if (key === null) return null;
+	const override = positiveInteger(status.target.maxConcurrentRequests);
+	if (override !== undefined) return { key, label: endpointLabel(key), limit: override, source: "override" };
+	const discovered = positiveInteger(status.probeCapabilities?.parallelSlots);
+	if (discovered !== undefined) return { key, label: endpointLabel(key), limit: discovered, source: "discovered" };
+	if (status.runtime?.tier !== "local-native" || UNBOUNDED_LOCAL_NATIVE_RUNTIMES.has(status.runtime.id)) return null;
+	return { key, label: endpointLabel(key), limit: 1, source: "local-native-default" };
+}
+
+function sourceRank(source: EndpointCapacitySource): number {
+	return source === "override" ? 2 : source === "discovered" ? 1 : 0;
+}
+
+/** Resolve one conservative limit per scheduler, preferring an explicit override. */
+export function endpointCapacitiesForStatuses(
+	statuses: ReadonlyArray<TargetStatus>,
+): Readonly<Record<string, EndpointCapacity>> {
+	const capacities: Record<string, EndpointCapacity> = {};
+	for (const status of statuses) {
+		const candidate = endpointCapacityForStatus(status);
+		if (candidate === null) continue;
+		const current = capacities[candidate.key];
+		if (
+			current === undefined ||
+			sourceRank(candidate.source) > sourceRank(current.source) ||
+			(sourceRank(candidate.source) === sourceRank(current.source) && candidate.limit < current.limit)
+		) {
+			capacities[candidate.key] = candidate;
+		}
+	}
+	return capacities;
+}
+
+/**
+ * The orchestrator's own request lives only in this process. It deliberately
+ * never enters dispatch-admission.json because process exit releases it.
+ */
+const foregroundStreams = new Map<string, number>();
+
+export function registerForegroundStream(endpointKey: string): () => void {
+	foregroundStreams.set(endpointKey, (foregroundStreams.get(endpointKey) ?? 0) + 1);
+	let held = true;
+	return () => {
+		if (!held) return;
+		held = false;
+		const next = (foregroundStreams.get(endpointKey) ?? 1) - 1;
+		if (next <= 0) foregroundStreams.delete(endpointKey);
+		else foregroundStreams.set(endpointKey, next);
+	};
+}
+
+export function foregroundStreamUsage(): Readonly<Record<string, number>> {
+	return Object.fromEntries(foregroundStreams);
+}

package/src/domains/providers/index.ts

@@ -27,6 +27,16 @@ export {
 export { AGENT_ROLE_TOOLS_REQUIRED_REASON, mergeCapabilities, supportsAgentRoleTools } from "./capabilities.js";
 export type { ProvidersContract, TargetHealth, TargetStatus } from "./contract.js";
 export { isDispatchEligibleRuntime, isOrchestratorEligibleRuntime, isTargetEligibleRuntime } from "./eligibility.js";
+export {
+	canonicalEndpointKey,
+	type EndpointCapacity,
+	type EndpointCapacitySource,
+	endpointCapacitiesForStatuses,
+	endpointCapacityForStatus,
+	endpointLabel,
+	foregroundStreamUsage,
+	registerForegroundStream,
+} from "./endpoint-capacity.js";
 export { ProvidersManifest } from "./manifest.js";
 export type { ModelCapabilityPatchTarget } from "./model-capabilities.js";
 export { applyModelCapabilityPatch, resolveModelCapabilities } from "./model-capabilities.js";