@iowarp/clio-coder 0.4.1 → 0.4.3

package/src/domains/dispatch/budget-envelope.ts

@@ -28,6 +28,17 @@ export interface BudgetEnvelopeReason {
 
 export interface RunToolBudgetEnvelope {
 	version: 1;
+	enforcement:
+		| {
+				classification: "native-per-tool";
+				perTool: "enforced";
+				clioControls: ReadonlyArray<"tool-calls" | "read-reserve" | "synthesis" | "attempt-cap">;
+		  }
+		| {
+				classification: "external-one-shot";
+				perTool: "unobserved-not-enforced";
+				clioControls: ReadonlyArray<"single-launch" | "wall-clock" | "output-cap" | "cancellation" | "result-contract">;
+		  };
 	policy: {
 		recipeId: string;
 		default: AgentBudgetPhase & { synthesis: boolean };
@@ -39,6 +50,15 @@ export interface RunToolBudgetEnvelope {
 	reasons: ReadonlyArray<BudgetEnvelopeReason>;
 }
 
+const NATIVE_CLIO_CONTROLS = ["tool-calls", "read-reserve", "synthesis", "attempt-cap"] as const;
+const EXTERNAL_CLIO_CONTROLS = [
+	"single-launch",
+	"wall-clock",
+	"output-cap",
+	"cancellation",
+	"result-contract",
+] as const;
+
 export type BudgetAdmissionDenialCode =
 	| "exact-recipe-policy"
 	| "recipe-maximum"
@@ -94,6 +114,8 @@ export function cloneDispatchBudgetRequest(value: unknown, prefix = "budget"): D
 }
 
 function freezeEnvelope(envelope: RunToolBudgetEnvelope): RunToolBudgetEnvelope {
+	Object.freeze(envelope.enforcement.clioControls);
+	Object.freeze(envelope.enforcement);
 	Object.freeze(envelope.policy.default);
 	Object.freeze(envelope.policy.maximum);
 	Object.freeze(envelope.policy);
@@ -172,6 +194,7 @@ export interface ResolveToolBudgetEnvelopeInput {
 	hasReadTool: boolean;
 	retry: boolean;
 	revision: boolean;
+	enforcement?: "native-per-tool" | "external-one-shot";
 }
 
 /** Resolve the one immutable envelope used by admission, enforcement, and evidence. */
@@ -253,6 +276,18 @@ export function resolveToolBudgetEnvelope(input: ResolveToolBudgetEnvelopeInput)
 	const authoredMaximum = input.policy.maximum ?? input.policy;
 	return freezeEnvelope({
 		version: 1,
+		enforcement:
+			input.enforcement === "external-one-shot"
+				? {
+						classification: "external-one-shot",
+						perTool: "unobserved-not-enforced",
+						clioControls: [...EXTERNAL_CLIO_CONTROLS],
+					}
+				: {
+						classification: "native-per-tool",
+						perTool: "enforced",
+						clioControls: [...NATIVE_CLIO_CONTROLS],
+					},
 		policy: {
 			recipeId: input.recipeId,
 			default: {
@@ -297,7 +332,11 @@ export function formatEffectiveBudget(envelope: RunToolBudgetEnvelope): string {
 	const revision = budget.revision
 		? `, result revision ${budget.revision.toolCalls}/${budget.revision.readReserve}`
 		: "";
-	return `${budget.toolCalls}/${budget.readReserve}${revision}, lifetime cap ${budget.hardCap}, synthesis=${budget.synthesis ? "on" : "off"}`;
+	const enforcement =
+		envelope.enforcement.classification === "external-one-shot"
+			? "external one-shot; per-tool unobserved/not enforced"
+			: "native per-tool enforced";
+	return `${budget.toolCalls}/${budget.readReserve}${revision}, lifetime cap ${budget.hardCap}, synthesis=${budget.synthesis ? "on" : "off"}; ${enforcement}`;
 }
 
 export function formatBudgetReasons(envelope: RunToolBudgetEnvelope): string {
@@ -314,6 +353,10 @@ const BUDGET_REASON_CODES: ReadonlySet<string> = new Set<BudgetEnvelopeReasonCod
 	"revision-growth-denied",
 ]);
 
+function isExactStringArray(value: unknown[], expected: readonly string[]): boolean {
+	return value.length === expected.length && value.every((item, index) => item === expected[index]);
+}
+
 /** Safely project an envelope that crossed a persistence or event boundary. */
 export function cloneRunToolBudgetEnvelope(value: unknown): RunToolBudgetEnvelope | undefined {
 	try {
@@ -373,8 +416,50 @@ export function cloneRunToolBudgetEnvelope(value: unknown): RunToolBudgetEnvelop
 			}
 			reasons.push({ code: reason.code as BudgetEnvelopeReasonCode, detail: reason.detail });
 		}
+		const enforcement = (() => {
+			if (value.enforcement === undefined) {
+				return {
+					classification: "native-per-tool" as const,
+					perTool: "enforced" as const,
+					clioControls: [...NATIVE_CLIO_CONTROLS],
+				};
+			}
+			if (!isRecord(value.enforcement) || !Array.isArray(value.enforcement.clioControls)) return null;
+			if (
+				Object.keys(value.enforcement).some(
+					(key) => key !== "classification" && key !== "perTool" && key !== "clioControls",
+				)
+			) {
+				return null;
+			}
+			if (
+				value.enforcement.classification === "external-one-shot" &&
+				value.enforcement.perTool === "unobserved-not-enforced" &&
+				isExactStringArray(value.enforcement.clioControls, EXTERNAL_CLIO_CONTROLS)
+			) {
+				return {
+					classification: "external-one-shot" as const,
+					perTool: "unobserved-not-enforced" as const,
+					clioControls: [...EXTERNAL_CLIO_CONTROLS],
+				};
+			}
+			if (
+				value.enforcement.classification === "native-per-tool" &&
+				value.enforcement.perTool === "enforced" &&
+				isExactStringArray(value.enforcement.clioControls, NATIVE_CLIO_CONTROLS)
+			) {
+				return {
+					classification: "native-per-tool" as const,
+					perTool: "enforced" as const,
+					clioControls: [...NATIVE_CLIO_CONTROLS],
+				};
+			}
+			return null;
+		})();
+		if (enforcement === null) return undefined;
 		return freezeEnvelope({
 			version: 1,
+			enforcement,
 			policy: {
 				recipeId,
 				default: { ...defaultPhase, synthesis: value.policy.default.synthesis },

package/src/domains/dispatch/capability-match.ts

@@ -34,6 +34,7 @@
 import type { ResultContract } from "../agents/result-contract.js";
 import type { AgentCapabilityClass, AgentSpec } from "../agents/spec.js";
 import { type AgentTaskType, classifyAgentTask } from "./agent-candidates.js";
+import type { DispatchIntent } from "./intent.js";
 
 /** Capability classes that cannot change the workspace, whatever the task says. */
 const READ_ONLY_CAPABILITY_CLASSES: ReadonlySet<AgentCapabilityClass> = new Set(["read-only", "verification"]);
@@ -75,6 +76,7 @@ const REPORTING_CONTRACT_KINDS: ReadonlySet<ResultContract["kind"]> = new Set([
 	"scout-report",
 	"verifier-report",
 	"research-report",
+	"world-knowledge-report",
 	"provenance-report",
 	"debugger-report",
 	"oracle-report",
@@ -112,6 +114,14 @@ export interface CapabilityMismatchInput {
 	resultContractKind: ResultContract["kind"] | null;
 	/** Installed recipes, used only to name a suggestion that actually resolves. */
 	specs: ReadonlyArray<AgentSpec>;
+	/**
+	 * The caller's typed intent, when it sent one. An intent that declares no
+	 * write roots and no expected outputs is the caller saying in the schema
+	 * that this run changes nothing, which outranks a verb the prose classifier
+	 * read as mutating ("write the failing test first" inside a survey question
+	 * refused a scout and cost the orchestrator a round).
+	 */
+	intent?: Pick<DispatchIntent, "writeRoots" | "expectedOutputs"> | null;
 }
 
 function suggestedSpecialist(taskType: AgentTaskType, specs: ReadonlyArray<AgentSpec>): string | null {
@@ -130,6 +140,7 @@ function suggestedSpecialist(taskType: AgentTaskType, specs: ReadonlyArray<Agent
  */
 export function assessCapabilityMismatch(input: CapabilityMismatchInput): CapabilityMismatch | null {
 	if (!READ_ONLY_CAPABILITY_CLASSES.has(input.capabilityClass)) return null;
+	if (input.intent && input.intent.writeRoots.length === 0 && input.intent.expectedOutputs.length === 0) return null;
 	const features = classifyAgentTask(input.task);
 	if (!MUTATING_TASK_TYPES.has(features.taskType)) return null;
 	const readShaped = READ_SHAPED_PATTERNS.some((pattern) => pattern.test(input.task));

package/src/domains/dispatch/capacity-lease.ts

@@ -481,6 +481,23 @@ export function capacityLeaseUsage(options?: { nowMs?: number; probe?: LeaseOwne
 	return { global: leases.length, nodes, endpoints, endpointHolders };
 }
 
+/** Coherent current endpoint occupancy, including held reservation waves.
+ * The caller still owns admission; process-local streams are not global leases.
+ */
+export function endpointCapacityUsage(): Readonly<Record<string, number>> {
+	return withStateFileLockSync(capacityStateLockPath(), () => {
+		const file = readCapacityStateUnsafe();
+		reclaim(file, Date.now(), defaultProbe);
+		const held = heldReservationUsage(file.reservations);
+		const usage: Record<string, number> = { ...foregroundStreamUsage() };
+		for (const [key, count] of Object.entries(held.endpoints)) usage[key] = (usage[key] ?? 0) + count;
+		for (const lease of file.leases) {
+			if (lease.endpointKey !== undefined) usage[lease.endpointKey] = (usage[lease.endpointKey] ?? 0) + 1;
+		}
+		return usage;
+	});
+}
+
 /**
  * Per-node lease counts for display and for advisory placement spreading. Every
  * read takes the admission state lock, so a render loop or a multi-node

package/src/domains/dispatch/contract.ts

@@ -86,6 +86,12 @@ export interface DispatchAdmissionObserver {
 	onAdmitted(run: { runId: string; pid: number | null; runtimeKind: RunEnvelope["runtimeKind"] }): void;
 }
 
+/** Invocation-owned admission bounds; never serialized into model-authored requests. */
+export interface DispatchPreparationOptions {
+	signal?: AbortSignal;
+	deadlineAt?: number;
+}
+
 /** Side-effect-free effective routing used to construct a dispatch approval artifact. */
 export interface DispatchPlanTaskResolution {
 	agentId: string;
@@ -225,6 +231,7 @@ export interface DispatchContract {
 	dispatch(
 		req: DispatchRequest,
 		observer?: DispatchAdmissionObserver,
+		preparation?: DispatchPreparationOptions,
 	): Promise<{
 		runId: string;
 		events: AsyncIterableIterator<unknown>;
@@ -232,7 +239,10 @@ export interface DispatchContract {
 	}>;
 
 	/** Spawn a group of dispatches and expose one merged batch event stream. */
-	dispatchBatch(reqs: ReadonlyArray<DispatchRequest>): Promise<{
+	dispatchBatch(
+		reqs: ReadonlyArray<DispatchRequest>,
+		preparation?: DispatchPreparationOptions,
+	): Promise<{
 		batchId: string;
 		/** Logical work ids, one per request in admission order. */
 		assignmentIds: ReadonlyArray<string>;