@narumitw/pi-subagents 0.53.0 → 1.0.0

package/src/settings/inspection.ts

@@ -0,0 +1,275 @@
+import type {
+	CompletionDelivery,
+	ConsultationCwdPolicy,
+	ConsultResourcePolicy,
+	DelegationCwdPolicy,
+	SubagentSettings,
+	SubagentTransportKind,
+} from "../agents/types.js";
+import { DEFAULT_MAX_PARALLEL_TASKS } from "../limits.js";
+import {
+	resolveStatefulLimits,
+	STATEFUL_LIMIT_FIELDS,
+	type StatefulLimitField,
+} from "../stateful-limits.js";
+import { hasOwn, isPlainObject } from "./schema.js";
+
+const DEFAULT_COMPLETION_DELIVERY: CompletionDelivery = "next-turn";
+export const DEFAULT_CONSULT_RESOURCE_POLICY: ConsultResourcePolicy = "project-context";
+export const DEFAULT_CONSULTATION_CWD_POLICY: ConsultationCwdPolicy = "anywhere";
+export const DEFAULT_DELEGATION_CWD_POLICY: DelegationCwdPolicy = "trusted-targets";
+
+export type DelegationWorkflow = "all" | "async-only" | "blocking-only" | "disabled";
+
+type SettingsSource = "default" | "user settings";
+
+export interface InspectedSubagentSettingsDocument {
+	path: string;
+	raw?: Record<string, unknown>;
+	settings?: SubagentSettings;
+	error?: string;
+}
+
+export interface DelegationWorkflowSettingsSnapshot {
+	path: string;
+	value: DelegationWorkflow;
+	source: SettingsSource;
+	error?: string;
+}
+
+export interface CompletionDeliverySettingsSnapshot {
+	path: string;
+	value: CompletionDelivery;
+	source: SettingsSource;
+	error?: string;
+}
+
+export interface StatefulTransportSettingsSnapshot {
+	path: string;
+	value: SubagentTransportKind;
+	source: SettingsSource;
+	error?: string;
+}
+
+export interface BlockingParallelLimitSettingsSnapshot {
+	path: string;
+	value: number;
+	source: SettingsSource;
+	error?: string;
+}
+
+export interface StatefulLimitFieldSnapshot {
+	value: number;
+	source: SettingsSource;
+}
+
+export interface StatefulLimitSettingsSnapshot {
+	path: string;
+	writePath: string;
+	values?: Record<StatefulLimitField, StatefulLimitFieldSnapshot>;
+	error?: string;
+}
+
+export interface ConsultResourceSettingsSnapshot {
+	path: string;
+	value: ConsultResourcePolicy;
+	source: SettingsSource;
+	error?: string;
+}
+
+export interface CwdPolicyFieldSnapshot<T> {
+	value: T;
+	source: SettingsSource;
+}
+
+export interface CwdPolicySettingsSnapshot {
+	path: string;
+	consultation: CwdPolicyFieldSnapshot<ConsultationCwdPolicy>;
+	delegation: CwdPolicyFieldSnapshot<DelegationCwdPolicy>;
+	error?: string;
+}
+
+export interface SubagentSettingsSnapshot {
+	path: string;
+	settings?: SubagentSettings;
+	source: SettingsSource;
+	error?: string;
+}
+
+export function resolveDelegationWorkflow(
+	blockingEnabled: boolean,
+	statefulEnabled: boolean,
+): DelegationWorkflow {
+	if (blockingEnabled && statefulEnabled) return "all";
+	if (statefulEnabled) return "async-only";
+	if (blockingEnabled) return "blocking-only";
+	return "disabled";
+}
+
+export function resolveBlockingMaxParallelTasks(settings?: SubagentSettings): number {
+	return settings?.blocking?.maxParallelTasks ?? DEFAULT_MAX_PARALLEL_TASKS;
+}
+
+export function buildSubagentSettingsSnapshot(
+	inspected: InspectedSubagentSettingsDocument,
+): SubagentSettingsSnapshot {
+	return {
+		path: inspected.path,
+		settings: inspected.settings,
+		source: inspected.settings ? "user settings" : "default",
+		...(inspected.error ? { error: inspected.error } : {}),
+	};
+}
+
+export function buildConsultResourceSettingsSnapshot(
+	inspected: InspectedSubagentSettingsDocument,
+): ConsultResourceSettingsSnapshot {
+	if (!inspected.raw || !inspected.settings) {
+		return {
+			path: inspected.path,
+			value: DEFAULT_CONSULT_RESOURCE_POLICY,
+			source: "default",
+			...(inspected.error ? { error: inspected.error } : {}),
+		};
+	}
+	const explicit =
+		isPlainObject(inspected.raw.consult) && hasOwn(inspected.raw.consult, "resources");
+	return {
+		path: inspected.path,
+		value: inspected.settings.consult?.resources ?? DEFAULT_CONSULT_RESOURCE_POLICY,
+		source: explicit ? "user settings" : "default",
+	};
+}
+
+export function buildCwdPolicySettingsSnapshot(
+	inspected: InspectedSubagentSettingsDocument,
+): CwdPolicySettingsSnapshot {
+	if (!inspected.raw || !inspected.settings) {
+		return {
+			path: inspected.path,
+			consultation: { value: DEFAULT_CONSULTATION_CWD_POLICY, source: "default" },
+			delegation: { value: DEFAULT_DELEGATION_CWD_POLICY, source: "default" },
+			...(inspected.error ? { error: inspected.error } : {}),
+		};
+	}
+	const rawPolicy = isPlainObject(inspected.raw.cwdPolicy) ? inspected.raw.cwdPolicy : undefined;
+	return {
+		path: inspected.path,
+		consultation: {
+			value: inspected.settings.cwdPolicy?.consultation ?? DEFAULT_CONSULTATION_CWD_POLICY,
+			source: rawPolicy && hasOwn(rawPolicy, "consultation") ? "user settings" : "default",
+		},
+		delegation: {
+			value: inspected.settings.cwdPolicy?.delegation ?? DEFAULT_DELEGATION_CWD_POLICY,
+			source: rawPolicy && hasOwn(rawPolicy, "delegation") ? "user settings" : "default",
+		},
+	};
+}
+
+export function buildDelegationWorkflowSettingsSnapshot(
+	inspected: InspectedSubagentSettingsDocument,
+): DelegationWorkflowSettingsSnapshot {
+	if (!inspected.raw || !inspected.settings) {
+		return {
+			path: inspected.path,
+			value: "all",
+			source: "default",
+			...(inspected.error ? { error: inspected.error } : {}),
+		};
+	}
+	const explicit =
+		(isPlainObject(inspected.raw.blocking) && hasOwn(inspected.raw.blocking, "enabled")) ||
+		(isPlainObject(inspected.raw.stateful) && hasOwn(inspected.raw.stateful, "enabled"));
+	return {
+		path: inspected.path,
+		value: resolveDelegationWorkflow(
+			inspected.settings.blocking?.enabled !== false,
+			inspected.settings.stateful?.enabled !== false,
+		),
+		source: explicit ? "user settings" : "default",
+	};
+}
+
+export function buildCompletionDeliverySettingsSnapshot(
+	inspected: InspectedSubagentSettingsDocument,
+): CompletionDeliverySettingsSnapshot {
+	if (!inspected.raw || !inspected.settings) {
+		return {
+			path: inspected.path,
+			value: DEFAULT_COMPLETION_DELIVERY,
+			source: "default",
+			...(inspected.error ? { error: inspected.error } : {}),
+		};
+	}
+	const explicit =
+		isPlainObject(inspected.raw.stateful) && hasOwn(inspected.raw.stateful, "completionDelivery");
+	return {
+		path: inspected.path,
+		value: inspected.settings.stateful?.completionDelivery ?? DEFAULT_COMPLETION_DELIVERY,
+		source: explicit ? "user settings" : "default",
+	};
+}
+
+export function buildStatefulTransportSettingsSnapshot(
+	inspected: InspectedSubagentSettingsDocument,
+): StatefulTransportSettingsSnapshot {
+	if (!inspected.raw || !inspected.settings) {
+		return {
+			path: inspected.path,
+			value: "subprocess",
+			source: "default",
+			...(inspected.error ? { error: inspected.error } : {}),
+		};
+	}
+	const explicit =
+		isPlainObject(inspected.raw.stateful) && hasOwn(inspected.raw.stateful, "transport");
+	return {
+		path: inspected.path,
+		value: inspected.settings.stateful?.transport ?? "subprocess",
+		source: explicit ? "user settings" : "default",
+	};
+}
+
+export function buildBlockingParallelLimitSettingsSnapshot(
+	inspected: InspectedSubagentSettingsDocument,
+): BlockingParallelLimitSettingsSnapshot {
+	if (!inspected.raw || !inspected.settings) {
+		return {
+			path: inspected.path,
+			value: DEFAULT_MAX_PARALLEL_TASKS,
+			source: "default",
+			...(inspected.error ? { error: inspected.error } : {}),
+		};
+	}
+	const explicit =
+		isPlainObject(inspected.raw.blocking) && hasOwn(inspected.raw.blocking, "maxParallelTasks");
+	return {
+		path: inspected.path,
+		value: resolveBlockingMaxParallelTasks(inspected.settings),
+		source: explicit ? "user settings" : "default",
+	};
+}
+
+export function buildStatefulLimitSettingsSnapshot(
+	inspected: InspectedSubagentSettingsDocument,
+	writePath: string,
+): StatefulLimitSettingsSnapshot {
+	if (inspected.error) {
+		return { path: inspected.path, writePath, error: inspected.error };
+	}
+	const resolved = resolveStatefulLimits(inspected.settings?.stateful);
+	const rawStateful = isPlainObject(inspected.raw?.stateful) ? inspected.raw.stateful : undefined;
+	return {
+		path: inspected.path,
+		writePath,
+		values: Object.fromEntries(
+			STATEFUL_LIMIT_FIELDS.map((field) => [
+				field,
+				{
+					value: resolved[field],
+					source: rawStateful && hasOwn(rawStateful, field) ? "user settings" : "default",
+				},
+			]),
+		) as unknown as Record<StatefulLimitField, StatefulLimitFieldSnapshot>,
+	};
+}

package/src/settings/schema.ts

@@ -0,0 +1,186 @@
+import {
+	CONSULT_RESOURCE_POLICIES,
+	CONSULTATION_CWD_POLICIES,
+	type ConsultationCwdPolicy,
+	type ConsultResourcePolicy,
+	DELEGATION_CWD_POLICIES,
+	type DelegationCwdPolicy,
+	isThinkingLevel,
+	type SubagentAgentConfig,
+	type SubagentSettings,
+} from "../agents/types.js";
+import { MAX_CONFIGURABLE_PARALLEL_TASKS, MAX_SUBAGENT_TIMEOUT_MS } from "../limits.js";
+import { isValidStatefulLimit, STATEFUL_LIMIT_FIELDS } from "../stateful-limits.js";
+
+export function hasOwn(obj: object, key: PropertyKey): boolean {
+	return Object.hasOwn(obj, key);
+}
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+export function isPositiveNumber(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 1;
+}
+
+export function isPositiveInteger(value: unknown): value is number {
+	return isPositiveNumber(value) && Number.isSafeInteger(value);
+}
+
+export function normalizeAgentSettings(value: unknown): SubagentAgentConfig | undefined {
+	if (!isPlainObject(value)) return undefined;
+
+	const config: SubagentAgentConfig = {};
+	let hasKnownField = false;
+
+	if (hasOwn(value, "tools")) {
+		if (!isStringArray(value.tools)) return undefined;
+		config.tools = value.tools;
+		hasKnownField = true;
+	}
+
+	if (hasOwn(value, "model")) {
+		if (value.model !== null && typeof value.model !== "string") return undefined;
+		config.model = value.model;
+		hasKnownField = true;
+	}
+
+	if (hasOwn(value, "thinkingLevel")) {
+		if (value.thinkingLevel !== null && !isThinkingLevel(value.thinkingLevel)) return undefined;
+		config.thinkingLevel = value.thinkingLevel;
+		hasKnownField = true;
+	}
+
+	if (hasOwn(value, "timeoutMs")) {
+		if (
+			value.timeoutMs !== null &&
+			(!isPositiveNumber(value.timeoutMs) || value.timeoutMs > MAX_SUBAGENT_TIMEOUT_MS)
+		) {
+			return undefined;
+		}
+		config.timeoutMs = value.timeoutMs;
+		hasKnownField = true;
+	}
+
+	return hasKnownField ? config : undefined;
+}
+
+export function normalizeSubagentSettings(value: unknown): SubagentSettings | undefined {
+	if (!isPlainObject(value)) return undefined;
+	const settings: SubagentSettings = {};
+	if (hasOwn(value, "agents")) {
+		if (!isPlainObject(value.agents)) return undefined;
+		const agents: Record<string, SubagentAgentConfig> = {};
+		for (const [name, rawConfig] of Object.entries(value.agents)) {
+			const config = normalizeAgentSettings(rawConfig);
+			if (config) agents[name] = config;
+		}
+		if (Object.keys(agents).length > 0) settings.agents = agents;
+	}
+	if (hasOwn(value, "blocking")) {
+		if (!isPlainObject(value.blocking)) return undefined;
+		const blocking: NonNullable<SubagentSettings["blocking"]> = {};
+		if (hasOwn(value.blocking, "enabled")) {
+			if (typeof value.blocking.enabled !== "boolean") return undefined;
+			blocking.enabled = value.blocking.enabled;
+		}
+		if (hasOwn(value.blocking, "maxParallelTasks")) {
+			if (
+				!isPositiveInteger(value.blocking.maxParallelTasks) ||
+				value.blocking.maxParallelTasks > MAX_CONFIGURABLE_PARALLEL_TASKS
+			) {
+				return undefined;
+			}
+			blocking.maxParallelTasks = value.blocking.maxParallelTasks;
+		}
+		settings.blocking = blocking;
+	}
+	if (hasOwn(value, "stateful")) {
+		if (!isPlainObject(value.stateful)) return undefined;
+		const runtime: NonNullable<SubagentSettings["stateful"]> = {};
+		if (hasOwn(value.stateful, "transport")) {
+			if (
+				value.stateful.transport !== "subprocess" &&
+				value.stateful.transport !== "in-process" &&
+				value.stateful.transport !== "rpc" &&
+				value.stateful.transport !== "auto"
+			) {
+				return undefined;
+			}
+			runtime.transport = value.stateful.transport;
+		}
+		if (hasOwn(value.stateful, "completionDelivery")) {
+			if (
+				value.stateful.completionDelivery !== "next-turn" &&
+				value.stateful.completionDelivery !== "auto-resume"
+			) {
+				return undefined;
+			}
+			runtime.completionDelivery = value.stateful.completionDelivery;
+		}
+		for (const key of STATEFUL_LIMIT_FIELDS) {
+			if (hasOwn(value.stateful, key)) {
+				if (!isValidStatefulLimit(key, value.stateful[key])) return undefined;
+				runtime[key] = value.stateful[key];
+			}
+		}
+		for (const key of ["maxMailboxMessages", "maxMailboxMessageBytes", "idleTtlMs"] as const) {
+			if (hasOwn(value.stateful, key)) {
+				if (!isPositiveInteger(value.stateful[key])) return undefined;
+				runtime[key] = value.stateful[key];
+			}
+		}
+		if (hasOwn(value.stateful, "retentionDays")) {
+			if (!isPositiveNumber(value.stateful.retentionDays)) return undefined;
+			runtime.retentionDays = value.stateful.retentionDays;
+		}
+		if (hasOwn(value.stateful, "enabled")) {
+			if (typeof value.stateful.enabled !== "boolean") return undefined;
+			runtime.enabled = value.stateful.enabled;
+		}
+		settings.stateful = runtime;
+	}
+	if (hasOwn(value, "consult")) {
+		if (!isPlainObject(value.consult)) return undefined;
+		const consult: NonNullable<SubagentSettings["consult"]> = {};
+		if (hasOwn(value.consult, "resources")) {
+			if (
+				typeof value.consult.resources !== "string" ||
+				!CONSULT_RESOURCE_POLICIES.includes(value.consult.resources as ConsultResourcePolicy)
+			) {
+				return undefined;
+			}
+			consult.resources = value.consult.resources as ConsultResourcePolicy;
+		}
+		settings.consult = consult;
+	}
+	if (hasOwn(value, "cwdPolicy")) {
+		if (!isPlainObject(value.cwdPolicy)) return undefined;
+		const cwdPolicy: NonNullable<SubagentSettings["cwdPolicy"]> = {};
+		if (hasOwn(value.cwdPolicy, "consultation")) {
+			if (
+				typeof value.cwdPolicy.consultation !== "string" ||
+				!CONSULTATION_CWD_POLICIES.includes(value.cwdPolicy.consultation as ConsultationCwdPolicy)
+			) {
+				return undefined;
+			}
+			cwdPolicy.consultation = value.cwdPolicy.consultation as ConsultationCwdPolicy;
+		}
+		if (hasOwn(value.cwdPolicy, "delegation")) {
+			if (
+				typeof value.cwdPolicy.delegation !== "string" ||
+				!DELEGATION_CWD_POLICIES.includes(value.cwdPolicy.delegation as DelegationCwdPolicy)
+			) {
+				return undefined;
+			}
+			cwdPolicy.delegation = value.cwdPolicy.delegation as DelegationCwdPolicy;
+		}
+		settings.cwdPolicy = cwdPolicy;
+	}
+	return settings;
+}