perstack 0.0.129 → 0.0.131

package/dist/bin/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { a as __toCommonJS, i as __require, n as __esmMin, o as __toESM, r as __exportAll, t as __commonJSMin } from "../chunk-DORXReHP.js";
-import { $ as intersection, A as runCommandInputSchema, At as NEVER, B as resolveModelTier, C as runSettingSchema, Ct as parseAsync, D as stopRunByDelegate, Dt as defineLazy, E as startRun, Et as clone, F as expertSchema, G as _enum, H as number$1, I as isCoordinatorExpert, J as any, K as _instanceof, L as validateDelegation, M as perstackConfigSchema, N as lockfileSchema, O as stopRunByError, Ot as normalizeParams, P as jobSchema, Pt as createId, Q as discriminatedUnion, R as checkpointSchema, S as runParamsSchema, St as parse$1, T as startGeneration, Tt as safeParseAsync$1, U as ZodIssueCode$1, V as resolveModelTierWithFallback, W as ZodOptional$1, X as boolean, Y as array$1, Z as custom, _ as parseExpertKey, _t as toJSONSchema, a as validateEventFilter, at as object$2, b as resumeFromStop, bt as $ZodObject, c as createBaseToolActivity, ct as record, d as completeRun, dt as tuple, et as lazy, f as continueToNextStep, ft as union, g as finishToolCall, gt as datetime, h as finishMcpTools, ht as safeParseAsync$2, i as createFilteredEventListener, it as number, j as startCommandInputSchema, jt as PerstackError, k as stopRunByInteractiveTool, kt as $constructor, l as createGeneralToolActivity, lt as strictObject, m as createStreamingEvent, mt as url, n as parseWithFriendlyError, nt as looseObject, o as getFilteredEnv, ot as optional, p as createRuntimeEvent, pt as unknown, q as _null, r as truncateText$1, rt as never, st as preprocess, t as createApiClient, tt as literal, u as callTools, ut as string, v as proceedToInteractiveTools, w as skipDelegates, wt as safeParse$1, x as retry, xt as $ZodType, y as resolveToolResults, z as knownModels } from "../dist-RHs5gh6F.js";
+import { $ as discriminatedUnion, A as stopRunByInteractiveTool, At as $constructor, B as knownModels, C as runParamsSchema, Ct as parse$1, D as startRun, Dt as clone, E as startGeneration, Et as safeParseAsync$1, F as jobSchema, Ft as createId, G as ZodOptional$1, H as resolveModelTierWithFallback, I as expertSchema, J as _null, K as _enum, L as isCoordinatorExpert, M as startCommandInputSchema, Mt as PerstackError, N as perstackConfigSchema, O as stopRunByDelegate, Ot as defineLazy, P as lockfileSchema, Q as custom, R as validateDelegation, S as retry, St as $ZodType, T as skipDelegates, Tt as safeParse$1, U as number$1, V as resolveModelTier, W as ZodIssueCode$1, X as array$1, Y as any, Z as boolean, _ as finishToolCall, _t as datetime, a as createFilteredEventListener, at as number, b as resolveToolResults, ct as preprocess, d as callTools, dt as string, et as intersection, f as completeRun, ft as tuple, g as finishMcpTools, gt as safeParseAsync$2, h as createStreamingEvent, ht as url, i as truncateText$1, it as never, j as runCommandInputSchema, jt as NEVER, k as stopRunByError, kt as normalizeParams, l as createBaseToolActivity, lt as record, m as createRuntimeEvent, mt as unknown, n as formatZodError, nt as literal, o as validateEventFilter, ot as object$2, p as continueToNextStep, pt as union, q as _instanceof, r as parseWithFriendlyError, rt as looseObject, s as getFilteredEnv, st as optional, t as createApiClient, tt as lazy, u as createGeneralToolActivity, ut as strictObject, v as parseExpertKey, vt as toJSONSchema, w as runSettingSchema, wt as parseAsync, x as resumeFromStop, xt as $ZodObject, y as proceedToInteractiveTools, z as checkpointSchema } from "../dist-C1wXMdbD.js";
 import { t as require_token_error } from "../token-error-Bru5BVnt.js";
 import fs, { constants, lstat, mkdir, open, readFile, stat, writeFile } from "node:fs/promises";
 import path, { dirname, extname } from "node:path";
@@ -1010,6 +1010,59 @@ async function findConfigPathRecursively(cwd) {
 		return await findConfigPathRecursively(path.dirname(cwd));
 	}
 }
+async function validatePerstackConfigFile(filePath) {
+	const errors = [];
+	let content;
+	try {
+		content = await readFile(path.resolve(process.cwd(), filePath), "utf-8");
+	} catch {
+		return {
+			valid: false,
+			errors: [`File not found: ${filePath}`]
+		};
+	}
+	let toml;
+	try {
+		toml = dist_default.parse(content);
+	} catch (e) {
+		return {
+			valid: false,
+			errors: [`TOML parse error: ${e instanceof Error ? e.message : String(e)}`]
+		};
+	}
+	const configResult = perstackConfigSchema.safeParse(toml);
+	if (!configResult.success) {
+		errors.push(formatZodError(configResult.error));
+		return {
+			valid: false,
+			errors
+		};
+	}
+	const config = configResult.data;
+	if (config.experts) for (const [name, expert] of Object.entries(config.experts)) {
+		const expertResult = expertSchema.safeParse({
+			key: name,
+			name,
+			version: expert.version ?? "1.0.0",
+			description: expert.description,
+			instruction: expert.instruction,
+			skills: expert.skills,
+			delegates: expert.delegates,
+			tags: expert.tags,
+			defaultModelTier: expert.defaultModelTier,
+			minRuntimeVersion: expert.minRuntimeVersion,
+			providerTools: expert.providerTools,
+			providerSkills: expert.providerSkills,
+			providerToolOptions: expert.providerToolOptions
+		});
+		if (!expertResult.success) errors.push(`Expert "${name}": ${formatZodError(expertResult.error)}`);
+	}
+	if (errors.length > 0) return {
+		valid: false,
+		errors
+	};
+	return { valid: true };
+}
 //#endregion
 //#region ../../packages/perstack-toml/src/lockfile.ts
 function loadLockfile(lockfilePath) {
@@ -1042,6 +1095,131 @@ function generateLockfileToml(lockfile) {
 	return dist_default.stringify(lockfile);
 }
 //#endregion
+//#region ../../packages/perstack-toml/src/schema-printer.ts
+function formatType(prop) {
+	if (prop.const) return `"${prop.const}"`;
+	if (prop.enum) return prop.enum.map((v) => `"${v}"`).join(" | ");
+	if (prop.oneOf) return prop.oneOf.map(formatType).filter(Boolean).join(" | ");
+	if (prop.type === "array" && prop.items) return `${formatType(prop.items)}[]`;
+	if (Array.isArray(prop.type)) return prop.type.join(" | ");
+	return prop.type ?? "any";
+}
+function formatConstraints(prop) {
+	const parts = [];
+	if (prop.minLength !== void 0) parts.push(`min ${prop.minLength}`);
+	if (prop.maxLength !== void 0) parts.push(`max ${prop.maxLength}`);
+	if (prop.minimum !== void 0) parts.push(`min ${prop.minimum}`);
+	if (prop.maximum !== void 0) parts.push(`max ${prop.maximum}`);
+	if (prop.pattern) parts.push(`pattern: ${prop.pattern}`);
+	return parts.length > 0 ? ` (${parts.join(", ")})` : "";
+}
+function printObjectFields(properties, required, indent = "") {
+	const lines = [];
+	for (const [name, prop] of Object.entries(properties)) {
+		const reqLabel = required.includes(name) ? "required" : "optional";
+		const type = formatType(prop);
+		const constraints = formatConstraints(prop);
+		lines.push(`${indent}${name.padEnd(24)} ${type.padEnd(20)} (${reqLabel})${constraints}`);
+	}
+	return lines.join("\n");
+}
+function printPerstackSchema() {
+	const jsonSchema = toJSONSchema(perstackConfigSchema, { unrepresentable: "any" });
+	const sections = [];
+	sections.push("# perstack.toml Schema Reference");
+	sections.push("");
+	if (jsonSchema.properties) {
+		sections.push("## Top-level fields");
+		sections.push("");
+		const topLevel = { ...jsonSchema.properties };
+		delete topLevel.experts;
+		sections.push(printObjectFields(topLevel, jsonSchema.required ?? []));
+		sections.push("");
+	}
+	const expertValueSchema = (jsonSchema.properties?.experts)?.additionalProperties;
+	if (expertValueSchema?.properties) {
+		sections.push("## Expert definition: [experts.\"expert-name\"]");
+		sections.push("");
+		sections.push(printObjectFields(expertValueSchema.properties, expertValueSchema.required ?? []));
+		sections.push("");
+		const skillValueSchema = expertValueSchema.properties.skills?.additionalProperties;
+		if (skillValueSchema?.oneOf) {
+			sections.push("## Skill types: [experts.\"name\".skills.\"skill-name\"]");
+			sections.push("");
+			for (const variant of skillValueSchema.oneOf) if (variant.properties?.type?.const) {
+				sections.push(`### ${variant.properties.type.const}`);
+				sections.push("");
+				sections.push(printObjectFields(variant.properties, variant.required ?? [], "  "));
+				sections.push("");
+			}
+		}
+	}
+	sections.push("## @perstack/base available tools");
+	sections.push("");
+	sections.push("Basic tools:");
+	sections.push("  readTextFile, readImageFile, readPdfFile, writeTextFile, editTextFile,");
+	sections.push("  exec, todo, clearTodo, attemptCompletion");
+	sections.push("");
+	sections.push("Skill & delegation management tools:");
+	sections.push("  addSkill, removeSkill, addDelegate, removeDelegate,");
+	sections.push("  createExpert, addDelegateFromConfig");
+	sections.push("");
+	sections.push("## Naming rules");
+	sections.push("");
+	sections.push("- Coordinators: kebab-case (e.g., \"my-expert\")");
+	sections.push("- Delegates: @coordinator/name (e.g., \"@my-expert/verify\")");
+	sections.push("- No self-delegation");
+	sections.push("- Delegates must be in-scope (same coordinator prefix)");
+	sections.push("- Delegates cannot delegate to their own coordinator");
+	sections.push("");
+	sections.push("## Example");
+	sections.push("");
+	sections.push("```toml");
+	sections.push("[experts.\"my-team\"]");
+	sections.push("version = \"1.0.0\"");
+	sections.push("defaultModelTier = \"high\"");
+	sections.push("description = \"Coordinates task execution and delegates to specialists\"");
+	sections.push("instruction = \"\"\"");
+	sections.push("Domain-specific constraints and coordination rules here.");
+	sections.push("\"\"\"");
+	sections.push("delegates = [\"@my-team/build\", \"@my-team/verify\"]");
+	sections.push("");
+	sections.push("[experts.\"my-team\".skills.\"@perstack/base\"]");
+	sections.push("type = \"mcpStdioSkill\"");
+	sections.push("command = \"npx\"");
+	sections.push("packageName = \"@perstack/base\"");
+	sections.push("pick = [\"readTextFile\", \"exec\", \"attemptCompletion\"]");
+	sections.push("");
+	sections.push("[experts.\"@my-team/build\"]");
+	sections.push("version = \"1.0.0\"");
+	sections.push("defaultModelTier = \"middle\"");
+	sections.push("description = \"Implements the core deliverable\"");
+	sections.push("instruction = \"\"\"");
+	sections.push("Domain constraints for this specialist.");
+	sections.push("\"\"\"");
+	sections.push("");
+	sections.push("[experts.\"@my-team/build\".skills.\"@perstack/base\"]");
+	sections.push("type = \"mcpStdioSkill\"");
+	sections.push("command = \"npx\"");
+	sections.push("packageName = \"@perstack/base\"");
+	sections.push("pick = [\"readTextFile\", \"writeTextFile\", \"editTextFile\", \"exec\", \"todo\", \"attemptCompletion\"]");
+	sections.push("```");
+	sections.push("");
+	sections.push("## Best Practices");
+	sections.push("");
+	sections.push("- Always set version, defaultModelTier, and description on every expert");
+	sections.push("- Always set an explicit pick list — omitting it grants ALL tools");
+	sections.push("- Instructions should contain only domain constraints the LLM cannot derive on its own");
+	sections.push("- Do not put implementation procedures, file paths, or data schemas in instructions");
+	sections.push("- Shorter instructions outperform longer ones — every line must earn its place");
+	sections.push("- Delegate names should describe function, not persona (/build, /verify, not /builder)");
+	sections.push("- Coordinators should have minimal pick lists (readTextFile, exec, attemptCompletion)");
+	sections.push("- Leaf experts doing file I/O need: readTextFile, writeTextFile, editTextFile, exec, todo, attemptCompletion");
+	sections.push("- Experts managing delegation need: addDelegateFromConfig, addDelegate, removeDelegate");
+	sections.push("");
+	return sections.join("\n");
+}
+//#endregion
 //#region ../../packages/installer/src/expert-resolver.ts
 function toRuntimeExpert(key, expert) {
 	const skills = Object.fromEntries(Object.entries(expert.skills ?? {}).map(([name, skill]) => {
@@ -21092,7 +21270,7 @@ async function expertVersionsHandler(scopeName, options) {
 }
 //#endregion
 //#region ../../packages/runtime/package.json
-var version$1 = "0.0.140";
+var version$1 = "0.0.141";
 //#endregion
 //#region ../../packages/runtime/src/helpers/usage.ts
 function createEmptyUsage() {
@@ -79577,7 +79755,7 @@ function validateRuntimeVersion(experts) {
 //#endregion
 //#region ../../packages/runtime/src/helpers/setup-experts.ts
 async function setupExperts(setting, resolveExpertToRun) {
-	const resolveFn = resolveExpertToRun ?? (await import("../resolve-expert-temTHQyu.js")).resolveExpertToRun;
+	const resolveFn = resolveExpertToRun ?? (await import("../resolve-expert-JQOam2_2.js")).resolveExpertToRun;
 	const { expertKey } = setting;
 	const experts = { ...setting.experts };
 	const clientOptions = {
@@ -92516,8 +92694,8 @@ function getCoordinatorMetaInstruction() {
     6. Aggregate results and clean up the workspace.
 
     Delegation guidelines:
-    - Be specific: include context, file paths, constraints, and expected output format. No vague delegations.
-    - Break large subtasks into focused units rather than overloading a single delegate.
+    - Be specific: include context, constraints, and expected output format. No vague delegations.
+    - A single delegate can handle a broad task if the role is straightforward. Only split into multiple delegates when responsibilities are genuinely distinct — unnecessary subdivision adds overhead without improving quality.
     - If no suitable delegate exists, use createExpert to create one, then addDelegate to register it.
 
     Workspace cleanup:
@@ -124512,7 +124690,7 @@ async function startHandler(expertKey, query, options, handlerOptions) {
 //#endregion
 //#region package.json
 var name = "perstack";
-var version = "0.0.129";
+var version = "0.0.131";
 var description = "PerStack CLI";
 //#endregion
 //#region bin/cli.ts
@@ -124564,6 +124742,17 @@ program.command("install").description("Generate perstack.lock with tool definit
 		envPath: options.envPath
 	});
 });
+program.command("validate").description("Validate a perstack.toml file against the schema").argument("<path>", "Path to perstack.toml file to validate").action(async (pathArg) => {
+	const result = await validatePerstackConfigFile(pathArg);
+	if (result.valid) console.log("Valid");
+	else {
+		for (const error of result.errors) console.error(error);
+		process.exit(1);
+	}
+});
+program.command("schema").description("Print the perstack.toml schema reference").action(() => {
+	console.log(printPerstackSchema());
+});
 function getParentOptions(cmd) {
 	const parent = cmd.parent?.opts();
 	return {