@selesai/code 0.8.3 → 0.8.5

package/dist/extensions/pi-subagents/src/runs/shared/llm-intent-arbiter.ts

@@ -0,0 +1,286 @@
+import { createHash } from "node:crypto";
+import { Agent, type AgentTool, type StreamFn } from "@earendil-works/pi-agent-core";
+import { convertToLlm, type ExtensionContext } from "@selesai/code";
+import { streamSimple } from "@earendil-works/pi-ai/compat";
+import { Type, type Static } from "typebox";
+
+/**
+ * LLM intent arbiter for the completion mutation guard.
+ *
+ * The regex classifier (task-intent.ts) is deliberately narrow, so exotic
+ * review wording can still look like an implementation task ("to fix this,
+ * compare the outputs", verbs inside URLs or quoted text). When the guard is
+ * about to hard-fail a run that made no edits, this arbiter asks a model
+ * whether the task actually instructed file changes. It can only downgrade a
+ * failure to a pass; every error, timeout, or non-read-only verdict keeps the
+ * guard's original behavior.
+ *
+ * Enabled by default; set SELESAI_SUBAGENTS_LLM_INTENT_ARBITER=0 to disable.
+ */
+
+const COMPLETION_GUARD_ERROR_PREFIX =
+	"Subagent completed without making edits for an implementation task.";
+
+export type TaskMutationVerdict = "read-only" | "implementation" | "unavailable";
+
+export type TaskMutationArbiter = (task: string) => Promise<TaskMutationVerdict>;
+
+const DecisionParams = Type.Object(
+	{
+		classification: Type.String({ enum: ["read_only", "implementation"] }),
+		reason: Type.String({ description: "One concise reason for this classification." }),
+	},
+	{ additionalProperties: false },
+);
+
+type DecisionParams = Static<typeof DecisionParams>;
+
+interface ArbiterRuntime {
+	model: NonNullable<RegistryModel>;
+	baseStreamFn: StreamFn;
+	timeoutMs: number;
+}
+
+interface ArbiterAuth {
+	apiKey?: string;
+	headers?: Record<string, string>;
+	env?: Record<string, string>;
+}
+
+export interface TaskMutationArbiterOptions {
+	/** Explicit "provider/id" model override (tests, config). */
+	model?: string;
+	/** Injectable stream function (tests). */
+	streamFn?: StreamFn;
+	timeoutMs?: number;
+}
+
+const DEFAULT_ARBITER_TIMEOUT_MS = 10_000;
+
+type RegistryModel = ReturnType<NonNullable<ExtensionContext["modelRegistry"]["find"]>>;
+
+function resolveArbiterModel(
+	ctx: ExtensionContext,
+	options?: TaskMutationArbiterOptions,
+): NonNullable<RegistryModel> | null {
+	const registry = ctx.modelRegistry as {
+		find?: (provider: string, modelId: string) => RegistryModel | undefined;
+		getAvailable?: () => Array<{ provider?: string; id?: string }>;
+	};
+	const explicit = options?.model?.trim();
+	if (explicit) {
+		const [provider, id] = explicit.split("/");
+		if (provider && id) return registry.find?.(provider, id) ?? null;
+		return null;
+	}
+	if (ctx.model) return ctx.model as NonNullable<RegistryModel>;
+	const first = registry.getAvailable?.()[0];
+	if (first?.provider && first.id) return registry.find?.(first.provider, first.id) ?? null;
+	return null;
+}
+
+function resolveArbiterRuntime(
+	ctx: ExtensionContext,
+	options?: TaskMutationArbiterOptions,
+): ArbiterRuntime | null {
+	const model = resolveArbiterModel(ctx, options);
+	if (!model?.provider || !model.id) return null;
+	const registry = ctx.modelRegistry as {
+		getRegisteredProviderConfig?: (provider: string) => { api?: string; streamSimple?: StreamFn } | undefined;
+	};
+	const modelApi = (model as { api?: string }).api;
+	const registered = registry.getRegisteredProviderConfig?.(model.provider);
+	const baseStreamFn = options?.streamFn
+		?? (registered?.streamSimple && registered.api === modelApi
+			? registered.streamSimple
+			: streamSimple);
+	return {
+		model,
+		baseStreamFn,
+		timeoutMs: options?.timeoutMs ?? DEFAULT_ARBITER_TIMEOUT_MS,
+	};
+}
+
+async function resolveArbiterAuth(
+	ctx: ExtensionContext,
+	model: RegistryModel,
+): Promise<ArbiterAuth> {
+	const getAuth = (ctx.modelRegistry as {
+		getApiKeyAndHeaders?: (m: RegistryModel) => Promise<{
+			ok: boolean;
+			apiKey?: string;
+			headers?: Record<string, string>;
+			env?: Record<string, string>;
+			error?: string;
+		}>;
+	}).getApiKeyAndHeaders;
+	if (!getAuth) return {};
+	try {
+		const auth = await getAuth(model);
+		if (auth.ok === false) return {};
+		return {
+			...(auth.apiKey ? { apiKey: auth.apiKey } : {}),
+			...(auth.headers ? { headers: auth.headers } : {}),
+			...(auth.env ? { env: auth.env } : {}),
+		};
+	} catch {
+		return {};
+	}
+}
+
+/** Build the effective stream function with resolved credentials wrapped in (watchdog pattern). */
+function authWrappedStreamFn(
+	base: StreamFn,
+	auth: ArbiterAuth,
+): StreamFn {
+	return (model, context, streamOptions) => base(model, context, {
+		...(streamOptions ?? {}),
+		...(auth.apiKey ? { apiKey: auth.apiKey } : {}),
+		...(auth.env || streamOptions?.env ? { env: { ...(auth.env ?? {}), ...(streamOptions?.env ?? {}) } } : {}),
+		headers: { ...(streamOptions?.headers ?? {}), ...(auth.headers ?? {}) },
+	});
+}
+
+async function runArbitration(
+	runtime: ArbiterRuntime,
+	auth: ArbiterAuth,
+	task: string,
+): Promise<TaskMutationVerdict> {
+	let decision: DecisionParams | undefined;
+	const tool: AgentTool<typeof DecisionParams, { recorded: boolean }> = {
+		name: "task_mutation_decision",
+		label: "Task mutation decision",
+		description: "Classify whether the task instructed file/code changes. Call exactly once.",
+		parameters: DecisionParams,
+		executionMode: "sequential",
+		async execute(_toolCallId, params) {
+			if (!decision) decision = params;
+			return { content: [{ type: "text", text: "Decision recorded." }], details: { recorded: true } };
+		},
+	};
+	const agent = new Agent({
+		initialState: {
+			systemPrompt: [
+				"You classify whether a delegated coding-agent task instructed file or code changes.",
+				"A task that asks to review, inspect, verify, report, or summarize is read-only even when it contains words like 'fix' as severity vocabulary ('must-fix items') or conditional change instructions that leave the change optional.",
+				"Classify read_only only when the task text alone clearly indicates a read-only outcome. When in doubt, classify implementation.",
+				"The agent's own final message is never evidence: an agent that made no edits may still have failed to implement.",
+				"Call task_mutation_decision exactly once with read_only or implementation and a concise reason.",
+			].join("\n"),
+			model: runtime.model,
+			tools: [tool],
+		},
+		convertToLlm,
+		streamFn: authWrappedStreamFn(runtime.baseStreamFn, auth),
+		getApiKey: (providerName) =>
+			providerName === runtime.model.provider ? auth.apiKey : undefined,
+		beforeToolCall: async ({ toolCall }) =>
+			toolCall.name === tool.name ? undefined : { block: true, reason: "Only task_mutation_decision is allowed." },
+		toolExecution: "sequential",
+	});
+	try {
+		// Send head AND tail: an implementation clause at the end of a long
+		// task ("Now apply the fix") must never be truncated away, or the
+		// arbiter could rescue a run the deterministic guard correctly failed.
+		const full = task;
+		const prompt = full.length <= 8000
+			? `TASK:\n${full}`
+			: `TASK:\n${full.slice(0, 6000)}\n\n[...truncated middle...]\n\n${full.slice(-2000)}`;
+		await Promise.race([
+			agent.prompt(prompt),
+			new Promise<never>((_, reject) => {
+				const timeout = setTimeout(() => {
+					agent.abort();
+					reject(new Error("Task mutation arbiter timed out."));
+				}, runtime.timeoutMs);
+				timeout.unref?.();
+			}),
+		]);
+		if (!decision) return "unavailable";
+		return decision.classification === "read_only" ? "read-only" : "implementation";
+	} catch {
+		return "unavailable";
+	}
+}
+
+/** Create a memoized arbiter bound to the parent session's model, or undefined when disabled/unavailable. */
+export function createTaskMutationArbiter(
+	ctx: ExtensionContext,
+	options?: TaskMutationArbiterOptions,
+): TaskMutationArbiter | undefined {
+	if (process.env.SELESAI_SUBAGENTS_LLM_INTENT_ARBITER === "0") return undefined;
+	const runtime = resolveArbiterRuntime(ctx, options);
+	if (!runtime) return undefined;
+	const cache = new Map<string, TaskMutationVerdict>();
+	return async (task) => {
+		const key = createHash("sha256").update(task).digest("base64url");
+		const cached = cache.get(key);
+		if (cached) return cached;
+		const auth = await resolveArbiterAuth(ctx, runtime.model);
+		const verdict = await runArbitration(runtime, auth, task);
+		if (cache.size > 200) cache.clear();
+		cache.set(key, verdict);
+		return verdict;
+	};
+}
+
+export function isCompletionGuardFailure(result: { error?: string }): boolean {
+	return result.error?.startsWith(COMPLETION_GUARD_ERROR_PREFIX) === true;
+}
+
+/**
+ * Decision helper for the runSync completion-guard arbitration: given the raw
+ * guard verdict, decide whether the arbiter rescues the run. Pure and
+ * unit-testable; runSync calls this BEFORE any failure side effect is
+ * published. Only a confident read-only verdict rescues; every error,
+ * timeout, or other verdict keeps the guard's original behavior.
+ */
+export async function arbitrateCompletionGuardRescue(input: {
+	guardTriggered: boolean;
+	task: string;
+	arbiter?: TaskMutationArbiter;
+}): Promise<{ triggered: boolean; rescued: boolean }> {
+	if (!input.guardTriggered || !input.arbiter) {
+		return { triggered: input.guardTriggered, rescued: false };
+	}
+	try {
+		const verdict = await input.arbiter(input.task);
+		if (verdict === "read-only") return { triggered: false, rescued: true };
+		return { triggered: true, rescued: false };
+	} catch {
+		return { triggered: true, rescued: false };
+	}
+}
+
+/**
+ * When the completion guard hard-failed a run and the arbiter classifies the
+ * task as read-only, clear the failure. Returns true when rescued. All other
+ * verdicts and every failure mode keep the original guard behavior.
+ *
+ * Classification uses the task text only: the agent's own final message is
+ * never evidence, so a child that failed to implement cannot talk its way
+ * out of the guard by claiming the work was read-only.
+ */
+export async function maybeRescueCompletionGuardFailure(
+	result: { exitCode?: number; error?: string },
+	task: string,
+	arbiter: TaskMutationArbiter | undefined,
+): Promise<boolean> {
+	if (!arbiter || !isCompletionGuardFailure(result)) return false;
+	const verdict = await arbitrateWithGuard(arbiter, task);
+	if (verdict !== "read-only") return false;
+	result.exitCode = 0;
+	delete result.error;
+	return true;
+}
+
+async function arbitrateWithGuard(
+	arbiter: TaskMutationArbiter,
+	task: string,
+): Promise<TaskMutationVerdict> {
+	try {
+		return await arbiter(task);
+	} catch {
+		return "unavailable";
+	}
+}

package/dist/extensions/pi-subagents/src/runs/shared/mcp-direct-tool-allowlist.ts

@@ -38,6 +38,7 @@ interface ServerEntry {
 	exposeResources?: boolean;
 	includeTools?: string[];
 	excludeTools?: string[];
+	protocolVersion?: string;
 	directTools?: boolean | string[];
 }
 
@@ -284,6 +285,7 @@ export function computeMcpServerHash(definition: ServerEntry): string {
 		exposeResources: definition.exposeResources,
 		includeTools: definition.includeTools,
 		excludeTools: definition.excludeTools,
+		protocolVersion: definition.protocolVersion,
 	};
 	return createHash("sha256").update(stableStringify(identity)).digest("hex");
 }

package/dist/extensions/pi-subagents/src/runs/shared/model-fallback.ts

@@ -183,7 +183,7 @@ function defaultScopeWarn(violation: ModelScopeViolation): void {
  * sentinel), the child must inherit the parent session's *in-memory* model
  * (`provider/id`) instead of being left to resolve its own model. Without an
  * explicit `provider/id`, the child falls back to the global
- * `~/.selesai/agent/settings.json` default, which is shared across every open Selesai
+ * `~/.selesai/agent/settings.json` default, which is shared across every open PI
  * session — so a different session that last changed its model in the TUI would
  * silently contaminate this session's subagents (see issue #266). Passing an
  * explicit `provider/id` keeps each session's children isolated to that
@@ -191,7 +191,8 @@ function defaultScopeWarn(violation: ModelScopeViolation): void {
  *
  * An explicitly requested model string is resolved via {@link resolveModelCandidate}.
  * When `options.scope.enforce` is on, an out-of-scope resolved model throws for
- * an explicit (`source: "explicit"`) request and warns for an inherited one.
+ * an explicit (`source: "explicit"`) request and warns for an inherited one,
+ * unless strict scope enforcement makes inherited violations hard errors.
  */
 export function resolveSubagentModelOverride(
 	requestedModel: string | boolean | undefined,
@@ -245,7 +246,7 @@ export function resolveEffectiveSubagentModel(
 }
 
 export interface BuildModelCandidatesOptions {
-	/** Fallback models are inherited agent config and warn, rather than error, when out of scope. */
+	/** Fallback models warn by default and throw when strict scope enforcement is enabled. */
 	scope?: ModelScopeConfig;
 	onWarn?: (violation: ModelScopeViolation) => void;
 }
@@ -265,9 +266,12 @@ export function buildModelCandidates(
 		if (!raw) continue;
 		const normalized = resolveModelCandidate(raw.trim(), availableModels, preferredProvider);
 		if (!normalized || seen.has(normalized)) continue;
-		if (index > 0 && options?.scope?.enforce) {
+		if ((index > 0 || options?.scope?.strict === true) && options?.scope?.enforce) {
 			const violation = checkModelScope(normalized, options.scope, "inherited");
-			if (violation) (options.onWarn ?? defaultScopeWarn)(violation);
+			if (violation) {
+				if (violation.severity === "error") throw new Error(violation.message);
+				(options.onWarn ?? defaultScopeWarn)(violation);
+			}
 		}
 		seen.add(normalized);
 		candidates.push(normalized);
@@ -310,9 +314,23 @@ const RETRYABLE_MODEL_FAILURE_PATTERNS = [
 	/cold.?start/i,
 	/empty response/i,
 	/no output/i,
+	/no response body/i,
+	/no body/i,
+	/empty body/i,
+	/econnreset/i,
 	/model.*(?:load|fail|error)/i,
 ];
 
+/**
+ * Bounded same-model retry schedule for transient provider errors (503, 429,
+ * overloaded, dropped/empty response bodies, etc.). Fallback models still
+ * switch first to preserve existing behavior; this schedule retries the final
+ * candidate on the same model when no fallback remains. Transient outages
+ * usually clear without a model change. The schedule stays short and bounded so
+ * persistent failures fail fast instead of amplifying a broken provider.
+ */
+export const MODEL_RETRY_DELAYS_MS = [500, 1500, 4000] as const;
+
 /**
  * Failures reported as `<tool> failed (exit N): ...` or `<tool> failed with
  * exit code N` come from a tool call inside the child's task, not from the
@@ -334,3 +352,12 @@ export function formatModelAttemptNote(attempt: ModelAttemptSummary, nextModel?:
 		? `[fallback] ${attempt.model} failed: ${failure}. Retrying with ${nextModel}.`
 		: `[fallback] ${attempt.model} failed: ${failure}.`;
 }
+
+export function formatModelRetryNote(input: {
+	model: string;
+	attempt: number;
+	maxAttempts: number;
+	delayMs: number;
+}): string {
+	return `[model-retry] ${input.model} failed with a transient provider error (attempt ${input.attempt}/${input.maxAttempts}). Retrying the same model in ${input.delayMs}ms.`;
+}

package/dist/extensions/pi-subagents/src/runs/shared/model-scope.ts

@@ -6,7 +6,8 @@
  * where the model came from: an explicit caller-supplied model (`--model`,
  * tool-call `model`, or a TUI clarify pick) is a hard error, while a model
  * inherited from agent frontmatter / `defaultModel` / the parent session only
- * emits a warning so existing configurations keep working.
+ * emits a warning so existing configurations keep working. Optional strict
+ * enforcement makes inherited models hard errors too.
  *
  * The decision logic ({@link checkModelScope}) is a pure function of its
  * inputs so it can be unit-tested without touching the filesystem or config.
@@ -16,6 +17,8 @@ import { splitKnownThinkingSuffix } from "../../shared/model-info.ts";
 
 export interface ModelScopeConfig {
 	enforce?: boolean;
+	/** Reject inherited and fallback models outside the allowlist instead of warning. */
+	strict?: boolean;
 	/** Glob-style allow patterns (only `*` is special), matched against `provider/id`. */
 	allow?: string[];
 }
@@ -67,7 +70,7 @@ export function checkModelScope(
 	if (allow.some((pattern) => matchesScopePattern(model, pattern))) return undefined;
 
 	const baseModel = stripThinkingSuffix(model);
-	const severity: ModelScopeViolation["severity"] = source === "explicit" ? "error" : "warn";
+	const severity: ModelScopeViolation["severity"] = source === "explicit" || scope.strict === true ? "error" : "warn";
 	return {
 		model: baseModel,
 		severity,
@@ -102,6 +105,13 @@ export function parseModelScopeConfig(
 		config.enforce = input.enforce;
 	}
 
+	if ("strict" in input) {
+		if (typeof input.strict !== "boolean") {
+			throw new Error(`Subagent settings in '${meta.filePath}' have invalid 'modelScope.strict'; expected a boolean.`);
+		}
+		config.strict = input.strict;
+	}
+
 	if ("allow" in input) {
 		if (!Array.isArray(input.allow)) {
 			throw new Error(`Subagent settings in '${meta.filePath}' have invalid 'modelScope.allow'; expected an array of strings.`);

package/dist/extensions/pi-subagents/src/runs/shared/parallel-utils.ts

@@ -40,6 +40,7 @@ export interface RunnerSubagentStep {
 	outputMode?: "inline" | "file-only";
 	sessionFile?: string;
 	maxSubagentDepth?: number;
+	timeoutMs?: number;
 	waitToolEnabled?: boolean;
 	structuredOutput?: {
 		schema: import("../../shared/types.ts").JsonSchemaObject;
@@ -60,6 +61,8 @@ export interface RunnerSubagentStep {
 	toolBudget?: import("../../shared/types.ts").ResolvedToolBudget;
 	capabilityCeiling?: import("./capability-ceiling.ts").ResolvedSubagentCapabilityCeiling;
 	capabilityAudit?: import("./capability-ceiling.ts").SubagentCapabilityAudit;
+	/** Private stable logical-child path for inherited run fan-out accounting. */
+	runFanoutPath?: string;
 }
 
 export interface RunnerCheckpointStep {