@iowarp/clio-coder 0.4.6 → 0.4.8

package/src/domains/dispatch/types.ts

@@ -1,3 +1,4 @@
+import type { WorkerContextProvenance } from "../context/worker/contract.js";
 /**
  * Shared run + receipt types for the dispatch domain (Phase 6 slice 2).
  *
@@ -43,6 +44,7 @@ export type RunOutcome =
 export type RunOutcomeCode =
 	| "vram_capacity_fit_failure"
 	| "worker_tool_call_cap_exhausted"
+	| "worker_context_exhausted"
 	| "loop_guard_tools_disabled_exhausted"
 	| "result_contract_exhausted"
 	| "worker_final_output_missing"
@@ -52,6 +54,7 @@ export function isRunOutcomeCode(value: unknown): value is RunOutcomeCode {
 	return (
 		value === "vram_capacity_fit_failure" ||
 		value === "worker_tool_call_cap_exhausted" ||
+		value === "worker_context_exhausted" ||
 		value === "loop_guard_tools_disabled_exhausted" ||
 		value === "result_contract_exhausted" ||
 		value === "worker_final_output_missing" ||
@@ -455,6 +458,7 @@ export interface RunEnvelope {
 	budget?: RunToolBudgetEnvelope;
 	/** Present only when a bounded parent briefing was sent as dynamic task data. */
 	briefing?: RunBriefingProvenance;
+	workerContext?: WorkerContextProvenance;
 	/** Sent steering provenance in stable per-run sequence order; prose is never persisted. */
 	steering?: ReadonlyArray<RunSteeringProvenance>;
 	targetId: string;
@@ -500,6 +504,7 @@ export interface RunEnvelope {
 	reasoningTokenCount?: number;
 	cacheReadTokenCount?: number;
 	cacheWriteTokenCount?: number;
+	cacheWrite1hTokenCount?: number;
 	staticShellHash?: string | null;
 	sessionShellHash?: string | null;
 	dynamicHash?: string | null;
@@ -801,6 +806,7 @@ export interface RunReceipt {
 	budget?: RunToolBudgetEnvelope;
 	/** Proof of briefing content without copying its prose into the receipt. */
 	briefing?: RunBriefingProvenance;
+	workerContext?: WorkerContextProvenance;
 	/** Sent steering provenance in stable per-run sequence order; prose is never persisted. */
 	steering?: ReadonlyArray<RunSteeringProvenance>;
 	targetId: string;
@@ -867,6 +873,7 @@ export interface RunReceipt {
 	outputTokenCount?: number;
 	cacheReadTokenCount?: number;
 	cacheWriteTokenCount?: number;
+	cacheWrite1hTokenCount?: number;
 	reasoningTokenCount?: number;
 	upstreamResponses?: RunReceiptUpstreamResponse[];
 	/** Bounded final/partial assistant output; absent when none was captured. */

package/src/domains/dispatch/validation.ts

@@ -1,3 +1,4 @@
+import { parseWorkerContextPolicy, type WorkerContextPolicy } from "../context/worker/contract.js";
 /**
  * Validate a dispatch job spec before it enters the queue. Pure function, no
  * I/O. Accepts unknown input so callers can hand it raw JSON or CLI args
@@ -74,6 +75,7 @@ export interface JobSpec {
 	task: string;
 	/** Bounded parent-composed context delivered as untrusted dynamic task data. */
 	briefing?: string;
+	context?: WorkerContextPolicy;
 	workerProfile?: string;
 	workerRuntime?: string;
 	delegationAgentId?: string;
@@ -188,6 +190,7 @@ const KNOWN_KEYS = new Set([
 	"executionRole",
 	"task",
 	"briefing",
+	"context",
 	"workerProfile",
 	"workerRuntime",
 	"delegationAgentId",
@@ -264,6 +267,14 @@ export function validateJobSpec(spec: unknown): Validated {
 		errors.push("executionRole must be a known execution role");
 	}
 
+	let context: WorkerContextPolicy | undefined;
+	if (spec.context !== undefined) {
+		try {
+			context = parseWorkerContextPolicy(spec.context);
+		} catch (error) {
+			errors.push(error instanceof Error ? error.message : String(error));
+		}
+	}
 	let briefing: string | undefined;
 	if ("briefing" in spec && spec.briefing !== undefined) {
 		if (typeof spec.briefing !== "string") {
@@ -560,6 +571,7 @@ export function validateJobSpec(spec: unknown): Validated {
 		task: task as string,
 	};
 	if (briefing !== undefined) out.briefing = briefing;
+	if (context !== undefined) out.context = context;
 	if (typeof spec.workerProfile === "string") out.workerProfile = spec.workerProfile;
 	if (typeof spec.workerRuntime === "string") out.workerRuntime = spec.workerRuntime;
 	if (typeof spec.delegationAgentId === "string") out.delegationAgentId = spec.delegationAgentId;

package/src/domains/dispatch/workspace-checkpoint.ts

@@ -14,7 +14,7 @@ export function workspaceCheckpointRef(kind: "loop" | "compete", identity: strin
  * The immutable ref makes retries idempotent and keeps the object alive across GC. */
 export function captureWorkspaceCheckpoint(cwd: string, ref: string, message: string): string {
 	if (!/^refs\/clio-coder\/(loop|compete)\/[a-f0-9]{64}$/.test(ref)) throw new Error("invalid workspace checkpoint ref");
-	const directory = mkdtempSync(join(tmpdir(), "clio-checkpoint-index-"));
+	const directory = mkdtempSync(join(tmpdir(), "clio-coder-checkpoint-index-"));
 	const env = buildSafeToolEnv({
 		GIT_INDEX_FILE: join(directory, "index"),
 		GIT_AUTHOR_NAME: "Clio checkpoint",

package/src/domains/eval/metrics/tracked.ts

@@ -42,6 +42,7 @@ export interface BuildEvalTrackedMetricsInput {
 }
 
 interface AssistantCall {
+	turnId: string;
 	timestamp: string | null;
 	payload: Record<string, unknown>;
 	promptCache: Record<string, unknown> | null;
@@ -175,7 +176,7 @@ export function buildEvalTrackedMetrics(input: BuildEvalTrackedMetricsInput): Ev
 			receiptToolErrors === undefined
 				? { value: ledgerToolErrors, source: "ledger" }
 				: { value: receiptToolErrors, source: "receipt" },
-		ttftMsFirstCall: firstCallTtft(calls),
+		ttftMsFirstCall: firstCallTtft(calls, input.ledgerEntries),
 		wallClockMs: wallClockMetric(input.receipt, input.fallbackWallClockMs),
 		contextTokensAtEnd: contextTokensAtEnd(calls, compactionEntries),
 		compactions: { value: compactionEntries.length, source: "ledger" },
@@ -210,6 +211,7 @@ function assistantCalls(entries: ReadonlyArray<SessionEntry>): AssistantCall[] {
 		if (promptCache === null && timing === null && usage === null) return [];
 		return [
 			{
+				turnId: entry.turnId,
 				timestamp: entry.payload.timestampEstimated === true ? null : entry.timestamp,
 				payload: entry.payload,
 				promptCache,
@@ -279,7 +281,24 @@ function reasoningMetric(
 	return measured ? { value: total, source: "ledger" } : { value: null, source: "estimated" };
 }
 
-function firstCallTtft(calls: ReadonlyArray<AssistantCall>): EvalSourcedNullableNumber {
+function firstCallTtft(
+	calls: ReadonlyArray<AssistantCall>,
+	entries: ReadonlyArray<SessionEntry>,
+): EvalSourcedNullableNumber {
+	// Parent links are causal evidence; wall-clock corrections must not promote
+	// a later call in the same session. Compare timestamps only across roots.
+	const parents = new Map(entries.map((entry) => [entry.turnId, entry.parentTurnId]));
+	const callIds = new Set(calls.map((call) => call.turnId));
+	const hasEarlierCall = (call: AssistantCall): boolean => {
+		const visited = new Set<string>([call.turnId]);
+		let parent = parents.get(call.turnId);
+		while (parent != null && !visited.has(parent)) {
+			if (callIds.has(parent)) return true;
+			visited.add(parent);
+			parent = parents.get(parent);
+		}
+		return false;
+	};
 	// Session directories are read by name, not by call time. Select without
 	// reordering the evidence or borrowing a later call's available timing.
 	let first: AssistantCall | undefined;
@@ -288,6 +307,7 @@ function firstCallTtft(calls: ReadonlyArray<AssistantCall>): EvalSourcedNullable
 		if (call.timestamp === null) return { value: null, source: "estimated" };
 		const at = Date.parse(call.timestamp);
 		if (!Number.isFinite(at)) return { value: null, source: "estimated" };
+		if (hasEarlierCall(call)) continue;
 		if (at < firstAt) {
 			first = call;
 			firstAt = at;

package/src/domains/evidence/failure-attribution.ts

@@ -18,6 +18,7 @@ export interface EvidenceFailureFacts {
  * model, harness, or environment by guesswork.
  */
 export function attributeEvidenceFailure(facts: EvidenceFailureFacts): EvidenceTag {
+	if (facts.outcomeCode === "worker_context_exhausted") return "context-overflow";
 	if (
 		facts.outcomeCode === "worker_tool_call_cap_exhausted" ||
 		facts.outcomeCode === "loop_guard_tools_disabled_exhausted"

package/src/domains/evidence/trust-status.ts

@@ -1,3 +1,4 @@
+import { parseWorkerContextProvenance } from "../../worker/context-seed.js";
 import type { GateDecisionArtifact, GateDecisionVerification } from "../dispatch/gate-decisions.js";
 import { RUN_RECEIPT_INTEGRITY_VERSION, verifyReceiptIntegrity } from "../dispatch/receipt-integrity.js";
 import type {
@@ -72,6 +73,7 @@ export type TrustArtifactKind =
 	| "gate_decision"
 	| "briefing"
 	| "project_context"
+	| "worker_context"
 	| "autonomy_policy"
 	| "finish_contract_evidence"
 	| "evidence_bundle"
@@ -206,6 +208,7 @@ const ARTIFACT_KINDS: ReadonlySet<string> = new Set([
 	"gate_decision",
 	"briefing",
 	"project_context",
+	"worker_context",
 	"autonomy_policy",
 	"finish_contract_evidence",
 	"evidence_bundle",
@@ -423,6 +426,7 @@ export type PersistedRunReceiptTrustFacts = Pick<RunReceipt, "runId"> &
 			| "validationGrounding"
 			| "briefing"
 			| "projectContext"
+			| "workerContext"
 			| "autonomyEnforcement"
 		>
 	>;
@@ -693,8 +697,21 @@ function recordedProjectContextHash(context: RunProjectContextProvenance | undef
 	return validNoneTierProjectContext(context) ? context.contentHash : undefined;
 }
 
+function validWorkerContext(value: unknown): boolean {
+	try {
+		parseWorkerContextProvenance(value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
 function contextArtifacts(receipt: PersistedRunReceiptTrustFacts): TrustArtifactReference[] {
 	const artifacts = [receiptReference(receipt)];
+	if (receipt.workerContext !== undefined && validWorkerContext(receipt.workerContext))
+		artifacts.push(
+			sha256Reference("worker_context", `${receipt.runId}:worker-context`, receipt.workerContext.contentHash),
+		);
 	if (receipt.briefing !== undefined && validBriefing(receipt.briefing)) {
 		artifacts.push(sha256Reference("briefing", `${receipt.runId}:briefing`, receipt.briefing.contentHash));
 	}
@@ -713,10 +730,12 @@ export function adaptRunReceiptContextStatus(
 	const artifacts = contextArtifacts(receipt);
 	const source = receiptSource(receipt);
 	const briefingInvalid = receipt.briefing !== undefined && !validBriefing(receipt.briefing);
-	if (briefingInvalid) return attributed("invalid", source, DISPATCH_AUTHORITY, artifacts);
+	if (briefingInvalid || (receipt.workerContext !== undefined && !validWorkerContext(receipt.workerContext)))
+		return attributed("invalid", source, DISPATCH_AUTHORITY, artifacts);
 	const context = receipt.projectContext;
 	if (context === undefined) {
-		if (receipt.briefing !== undefined) return attributed("recorded", source, DISPATCH_AUTHORITY, artifacts);
+		if (receipt.briefing !== undefined || receipt.workerContext !== undefined)
+			return attributed("recorded", source, DISPATCH_AUTHORITY, artifacts);
 		return attributed("unknown", compatibilitySource(receipt, "projectContext"), COMPATIBILITY_AUTHORITY, artifacts);
 	}
 	if (context.tier === "none") {
@@ -724,7 +743,7 @@ export function adaptRunReceiptContextStatus(
 		if (bare) {
 			// Nothing structured was sent: the axis does not apply unless a
 			// briefing was recorded, which is context of its own.
-			return receipt.briefing === undefined
+			return receipt.briefing === undefined && receipt.workerContext === undefined
 				? attributed("not_applicable", source, DISPATCH_AUTHORITY, artifacts)
 				: attributed("recorded", source, DISPATCH_AUTHORITY, artifacts);
 		}

package/src/domains/extensions/command-schema.ts

@@ -0,0 +1,145 @@
+import { lstatSync, realpathSync } from "node:fs";
+import path from "node:path";
+import type { ExtensionCapabilities, ExtensionCommandTool } from "./types.js";
+
+const TOOL_KEYS = new Set([
+	"name",
+	"description",
+	"runtime",
+	"entrypoint",
+	"inputSchema",
+	"timeoutMs",
+	"maxOutputBytes",
+]);
+const SCHEMA_KEYS = new Set([
+	"type",
+	"description",
+	"properties",
+	"required",
+	"additionalProperties",
+	"items",
+	"enum",
+	"minimum",
+	"maximum",
+	"minLength",
+	"maxLength",
+	"minItems",
+	"maxItems",
+]);
+const TYPES = new Set(["object", "array", "string", "number", "integer", "boolean", "null"]);
+
+function record(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+export function extensionToolName(id: string, name: string): string {
+	return `extension_${id}__${name}`;
+}
+
+function validateSchema(value: unknown, depth = 0): asserts value is Record<string, unknown> {
+	if (depth > 12 || !record(value))
+		throw new Error("inputSchema must be a JSON schema object with at most 12 nesting levels");
+	for (const key of Object.keys(value)) {
+		if (!SCHEMA_KEYS.has(key)) throw new Error(`unsupported inputSchema keyword '${key}'`);
+	}
+	if (typeof value.type !== "string" || !TYPES.has(value.type))
+		throw new Error("inputSchema.type must be a supported JSON type");
+	if (value.description !== undefined && typeof value.description !== "string")
+		throw new Error("inputSchema.description must be a string");
+	if (
+		value.enum !== undefined &&
+		(!Array.isArray(value.enum) ||
+			value.enum.length === 0 ||
+			value.enum.some((item) => item !== null && typeof item === "object"))
+	) {
+		throw new Error("inputSchema.enum must contain JSON scalar values");
+	}
+	for (const key of ["minimum", "maximum", "minLength", "maxLength", "minItems", "maxItems"]) {
+		if (value[key] !== undefined && (typeof value[key] !== "number" || !Number.isFinite(value[key])))
+			throw new Error(`inputSchema.${key} must be finite`);
+	}
+	if (value.type === "object") {
+		if (!record(value.properties) || value.additionalProperties !== false)
+			throw new Error("object inputSchema requires properties and additionalProperties: false");
+		for (const [key, child] of Object.entries(value.properties)) {
+			if (["__proto__", "constructor", "prototype"].includes(key)) throw new Error("unsafe inputSchema property name");
+			validateSchema(child, depth + 1);
+		}
+		if (
+			value.required !== undefined &&
+			(!Array.isArray(value.required) ||
+				value.required.some((key) => typeof key !== "string" || !Object.hasOwn(value.properties as object, key)))
+		) {
+			throw new Error("inputSchema.required must name declared properties");
+		}
+	} else if (value.type === "array") {
+		validateSchema(value.items, depth + 1);
+	}
+}
+
+export function parseExtensionCapabilities(value: unknown, id: string): ExtensionCapabilities {
+	if (
+		!record(value) ||
+		Object.keys(value).some((key) => key !== "tools") ||
+		!Array.isArray(value.tools) ||
+		value.tools.length === 0 ||
+		value.tools.length > 32
+	) {
+		throw new Error("capabilities must contain tools with between 1 and 32 command declarations");
+	}
+	if (id.includes("__")) throw new Error("v2 extension id cannot contain double underscores");
+	const names = new Set<string>();
+	const tools: ExtensionCommandTool[] = value.tools.map((tool) => {
+		if (!record(tool)) throw new Error("capabilities.tools entries must be objects");
+		for (const key of Object.keys(tool)) if (!TOOL_KEYS.has(key)) throw new Error(`unknown command tool key '${key}'`);
+		if (typeof tool.name !== "string" || !/^[a-z][a-z0-9_]*$/.test(tool.name) || tool.name.includes("__"))
+			throw new Error("command tool name must use lowercase letters, digits, and single underscores");
+		const name = extensionToolName(id, tool.name);
+		if (name.length > 64 || !/^[a-zA-Z0-9_-]+$/.test(name))
+			throw new Error("qualified command tool name must use provider-safe characters and fit 64 characters");
+		if (names.has(name)) throw new Error(`duplicate command tool name '${name}'`);
+		names.add(name);
+		if (typeof tool.description !== "string" || tool.description.trim().length === 0 || tool.description.length > 2000)
+			throw new Error("command tool description must contain 1 to 2000 characters");
+		if (tool.runtime !== "node" && tool.runtime !== "python3")
+			throw new Error("command tool runtime must be node or python3");
+		if (
+			typeof tool.entrypoint !== "string" ||
+			tool.entrypoint.includes("\0") ||
+			tool.entrypoint.includes("\\") ||
+			path.isAbsolute(tool.entrypoint) ||
+			tool.entrypoint.split("/").some((part) => part === ".." || part === "." || part === "")
+		)
+			throw new Error("command tool entrypoint must be a contained relative file path");
+		validateSchema(tool.inputSchema);
+		if (tool.inputSchema.type !== "object") throw new Error("command tool inputSchema root must be object");
+		for (const [key, maximum] of [
+			["timeoutMs", 300000],
+			["maxOutputBytes", 1048576],
+		] as const) {
+			const limit = tool[key];
+			if (limit !== undefined && (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1 || limit > maximum))
+				throw new Error(`command tool ${key} must be between 1 and ${maximum}`);
+		}
+		return structuredClone(tool) as unknown as ExtensionCommandTool;
+	});
+	return { tools };
+}
+
+/** Entry paths must resolve to ordinary package files, including every parent directory. */
+export function resolveExtensionEntrypoint(root: string, entrypoint: string): string {
+	const canonicalRoot = realpathSync(root);
+	let cursor = canonicalRoot;
+	for (const segment of entrypoint.split("/")) {
+		if (segment === ".." || segment === "." || segment.length === 0)
+			throw new Error("invalid command entrypoint segment");
+		cursor = path.join(cursor, segment);
+		if (lstatSync(cursor).isSymbolicLink()) throw new Error("command entrypoint cannot contain symbolic links");
+	}
+	const stat = lstatSync(cursor);
+	if (!stat.isFile() || stat.nlink !== 1) throw new Error("command entrypoint must be an ordinary file with one link");
+	const relative = path.relative(canonicalRoot, realpathSync(cursor));
+	if (relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+		throw new Error("command entrypoint escapes extension root");
+	return cursor;
+}

package/src/domains/extensions/command-tools.ts

@@ -0,0 +1,15 @@
+import type { DynamicToolName } from "../../core/tool-names.js";
+import { extensionToolName } from "./command-schema.js";
+import { listInstalledExtensions } from "./state.js";
+import { isLoadableExtension } from "./types.js";
+
+/** Available names for dispatch planning; registry construction re-verifies captured declarations. */
+export function enabledHarnessExtensionToolNames(cwd = process.cwd()): ReadonlySet<DynamicToolName> {
+	return new Set(
+		listInstalledExtensions(cwd)
+			.filter(isLoadableExtension)
+			.flatMap((entry) =>
+				(entry.capabilities?.tools ?? []).map((tool) => extensionToolName(entry.id, tool.name) as DynamicToolName),
+			),
+	);
+}

package/src/domains/extensions/compatibility.ts

@@ -66,6 +66,13 @@ function parseSemVer(value: string): SemVer | null {
 	return { major, minor, patch, prerelease: parsedPrerelease };
 }
 
+/** Exact, bounded manifest version; range conveniences such as a v prefix are excluded. */
+export function isSemanticVersion(value: unknown): value is string {
+	return (
+		typeof value === "string" && value.length <= MAX_RANGE_CHARS && /^[0-9]/.test(value) && parseSemVer(value) !== null
+	);
+}
+
 function parsePart(value: string | undefined): number | null {
 	if (value === undefined || value === "x" || value === "X" || value === "*") return null;
 	const parsed = Number(value);

package/src/domains/extensions/contract.ts

@@ -6,8 +6,6 @@ import type {
 	ExtensionListOptions,
 	ExtensionMutationResult,
 	ExtensionReloadPrepareResult,
-	ExtensionResourceKind,
-	ExtensionResourceRoot,
 	ExtensionSnapshot,
 	InstalledExtension,
 } from "./manager.js";
@@ -19,8 +17,6 @@ export interface ExtensionsContract extends DomainContract {
 	enable(id: string, options?: ExtensionListOptions): ExtensionMutationResult;
 	disable(id: string, options?: ExtensionListOptions): ExtensionMutationResult;
 	remove(id: string, options?: ExtensionListOptions): ExtensionMutationResult;
-	/** Committed projection for the bundle's cwd; ephemeral generation-0 build for any other cwd. */
-	resourceRoots(kind: ExtensionResourceKind, cwd?: string): ExtensionResourceRoot[];
 	snapshot(): ExtensionSnapshot | null;
 	generation(): number;
 	/**