@perstack/core 0.0.54 → 0.0.56

package/dist/src/index.js

@@ -1,29 +1,1983 @@
-export * from "./adapters/index.js";
-export * from "./constants/constants.js";
-export * from "./errors.js";
-export * from "./known-models/index.js";
-export * from "./schemas/activity.js";
-export * from "./schemas/checkpoint.js";
-export * from "./schemas/expert.js";
-export * from "./schemas/job.js";
-export * from "./schemas/lockfile.js";
-export * from "./schemas/message.js";
-export * from "./schemas/message-part.js";
-export * from "./schemas/perstack-toml.js";
-export * from "./schemas/provider-config.js";
-export * from "./schemas/provider-tools.js";
-export * from "./schemas/run-command.js";
-export * from "./schemas/runtime.js";
-export * from "./schemas/runtime-version.js";
-export * from "./schemas/skill.js";
-export * from "./schemas/skill-manager.js";
-export * from "./schemas/step.js";
-export * from "./schemas/tool-call.js";
-export * from "./schemas/tool-result.js";
-export * from "./schemas/usage.js";
-export * from "./utils/activity.js";
-export * from "./utils/env-filter.js";
-export * from "./utils/event-filter.js";
-export * from "./utils/expert-type.js";
-export * from "./utils/zod-error.js";
+import { createId } from "@paralleldrive/cuid2";
+import { z } from "zod";
+
+//#region src/adapters/event-creators.ts
+function createEmptyUsage() {
+	return {
+		inputTokens: 0,
+		outputTokens: 0,
+		reasoningTokens: 0,
+		totalTokens: 0,
+		cachedInputTokens: 0
+	};
+}
+function createNormalizedCheckpoint(params) {
+	const { jobId, runId, expert, output } = params;
+	return {
+		id: createId(),
+		jobId,
+		runId,
+		status: "completed",
+		stepNumber: 1,
+		messages: [{
+			id: createId(),
+			type: "expertMessage",
+			contents: [{
+				type: "textPart",
+				id: createId(),
+				text: output
+			}]
+		}],
+		expert: {
+			key: expert.key,
+			name: expert.name,
+			version: expert.version
+		},
+		usage: createEmptyUsage()
+	};
+}
+function createStartRunEvent(jobId, runId, expertKey, checkpoint) {
+	return {
+		type: "startRun",
+		id: createId(),
+		expertKey,
+		timestamp: Date.now(),
+		jobId,
+		runId,
+		stepNumber: checkpoint.stepNumber,
+		initialCheckpoint: checkpoint,
+		inputMessages: []
+	};
+}
+function createRuntimeInitEvent(jobId, runId, expertName, version, query) {
+	return {
+		type: "initializeRuntime",
+		id: createId(),
+		timestamp: Date.now(),
+		jobId,
+		runId,
+		runtimeVersion: version,
+		expertName,
+		experts: [],
+		model: "local:default",
+		maxRetries: 0,
+		timeout: 0,
+		query
+	};
+}
+function createCompleteRunEvent(jobId, runId, expertKey, checkpoint, output, startedAt) {
+	const lastMessage = checkpoint.messages[checkpoint.messages.length - 1];
+	return {
+		type: "completeRun",
+		id: createId(),
+		expertKey,
+		timestamp: Date.now(),
+		jobId,
+		runId,
+		stepNumber: checkpoint.stepNumber,
+		checkpoint,
+		step: {
+			stepNumber: checkpoint.stepNumber,
+			newMessages: lastMessage ? [lastMessage] : [],
+			usage: createEmptyUsage(),
+			startedAt: startedAt ?? Date.now()
+		},
+		text: output,
+		usage: createEmptyUsage()
+	};
+}
+function createCallToolsEvent(jobId, runId, expertKey, stepNumber, toolCalls, _checkpoint) {
+	const expertMessage = {
+		id: createId(),
+		type: "expertMessage",
+		contents: []
+	};
+	return {
+		type: "callTools",
+		id: createId(),
+		expertKey,
+		timestamp: Date.now(),
+		jobId,
+		runId,
+		stepNumber,
+		newMessage: expertMessage,
+		toolCalls,
+		usage: createEmptyUsage()
+	};
+}
+function createResolveToolResultsEvent(jobId, runId, expertKey, stepNumber, toolResults) {
+	return {
+		type: "resolveToolResults",
+		id: createId(),
+		expertKey,
+		timestamp: Date.now(),
+		jobId,
+		runId,
+		stepNumber,
+		toolResults
+	};
+}
+function createToolMessage(toolCallId, toolName, resultText) {
+	return {
+		id: createId(),
+		type: "toolMessage",
+		contents: [{
+			type: "toolResultPart",
+			id: createId(),
+			toolCallId,
+			toolName,
+			contents: [{
+				type: "textPart",
+				id: createId(),
+				text: resultText
+			}]
+		}]
+	};
+}
+
+//#endregion
+//#region src/constants/constants.ts
+const defaultPerstackApiBaseUrl = "https://api.perstack.ai";
+const expertKeyRegex = /^((?:@[a-z0-9][a-z0-9_.-]*\/)?[a-z0-9][a-z0-9_.-]*)(?:@((?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[\w.-]+)?(?:\+[\w.-]+)?)|@([a-z0-9][a-z0-9_.-]*))?$/;
+const expertNameRegex = /^(@[a-z0-9][a-z0-9_-]*\/)?[a-z0-9][a-z0-9_-]*$/;
+const expertVersionRegex = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[\w.-]+)?(?:\+[\w.-]+)?$/;
+const tagNameRegex = /^[a-z0-9][a-z0-9_-]*$/;
+const maxExpertNameLength = 255;
+const defaultMaxRetries = 5;
+const defaultTimeout = 5 * 1e3 * 60;
+const maxSkillNameLength = 255;
+const maxSkillToolNameLength = 255;
+
+//#endregion
+//#region src/errors.ts
+var PerstackError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "PerstackError";
+	}
+};
+
+//#endregion
+//#region src/known-models/index.ts
+const knownModels = [
+	{
+		provider: "anthropic",
+		models: [
+			{
+				name: "claude-opus-4-6",
+				contextWindow: 2e5,
+				maxOutputTokens: 128e3
+			},
+			{
+				name: "claude-opus-4-5",
+				contextWindow: 2e5,
+				maxOutputTokens: 32e3
+			},
+			{
+				name: "claude-opus-4-1",
+				contextWindow: 2e5,
+				maxOutputTokens: 32e3
+			},
+			{
+				name: "claude-opus-4-20250514",
+				contextWindow: 2e5,
+				maxOutputTokens: 32e3
+			},
+			{
+				name: "claude-sonnet-4-5",
+				contextWindow: 2e5,
+				maxOutputTokens: 64e3
+			},
+			{
+				name: "claude-sonnet-4-20250514",
+				contextWindow: 2e5,
+				maxOutputTokens: 64e3
+			},
+			{
+				name: "claude-3-7-sonnet-20250219",
+				contextWindow: 2e5,
+				maxOutputTokens: 64e3
+			},
+			{
+				name: "claude-haiku-4-5",
+				contextWindow: 2e5,
+				maxOutputTokens: 8192
+			},
+			{
+				name: "claude-3-5-haiku-latest",
+				contextWindow: 2e5,
+				maxOutputTokens: 8192
+			}
+		]
+	},
+	{
+		provider: "google",
+		models: [
+			{
+				name: "gemini-3-flash-preview",
+				contextWindow: 1048576,
+				maxOutputTokens: 65536
+			},
+			{
+				name: "gemini-3-pro-preview",
+				contextWindow: 1048576,
+				maxOutputTokens: 65536
+			},
+			{
+				name: "gemini-2.5-pro",
+				contextWindow: 1048576,
+				maxOutputTokens: 65536
+			},
+			{
+				name: "gemini-2.5-flash",
+				contextWindow: 1048576,
+				maxOutputTokens: 65536
+			},
+			{
+				name: "gemini-2.5-flash-lite",
+				contextWindow: 1048576,
+				maxOutputTokens: 65536
+			}
+		]
+	},
+	{
+		provider: "openai",
+		models: [
+			{
+				name: "gpt-5",
+				contextWindow: 4e5,
+				maxOutputTokens: 128e3
+			},
+			{
+				name: "gpt-5-mini",
+				contextWindow: 4e5,
+				maxOutputTokens: 128e3
+			},
+			{
+				name: "gpt-5-nano",
+				contextWindow: 4e5,
+				maxOutputTokens: 128e3
+			},
+			{
+				name: "gpt-5.2",
+				contextWindow: 4e5,
+				maxOutputTokens: 128e3
+			},
+			{
+				name: "gpt-5.2-pro",
+				contextWindow: 4e5,
+				maxOutputTokens: 128e3
+			},
+			{
+				name: "gpt-5.1",
+				contextWindow: 4e5,
+				maxOutputTokens: 128e3
+			},
+			{
+				name: "gpt-5-chat-latest",
+				contextWindow: 128e3,
+				maxOutputTokens: 16384
+			},
+			{
+				name: "o4-mini",
+				contextWindow: 2e5,
+				maxOutputTokens: 1e5
+			},
+			{
+				name: "o3",
+				contextWindow: 2e5,
+				maxOutputTokens: 1e4
+			},
+			{
+				name: "o3-mini",
+				contextWindow: 2e5,
+				maxOutputTokens: 1e4
+			},
+			{
+				name: "gpt-4.1",
+				contextWindow: 1047576,
+				maxOutputTokens: 32768
+			}
+		]
+	},
+	{
+		provider: "deepseek",
+		models: [{
+			name: "deepseek-chat",
+			contextWindow: 128e3,
+			maxOutputTokens: 8192
+		}, {
+			name: "deepseek-reasoner",
+			contextWindow: 128e3,
+			maxOutputTokens: 64e3
+		}]
+	},
+	{
+		provider: "ollama",
+		models: [
+			{
+				name: "gpt-oss:20b",
+				contextWindow: 131072,
+				maxOutputTokens: 131072
+			},
+			{
+				name: "gpt-oss:120b",
+				contextWindow: 131072,
+				maxOutputTokens: 131072
+			},
+			{
+				name: "gemma3:1b",
+				contextWindow: 32e3,
+				maxOutputTokens: 32e3
+			},
+			{
+				name: "gemma3:4b",
+				contextWindow: 128e3,
+				maxOutputTokens: 128e3
+			},
+			{
+				name: "gemma3:12b",
+				contextWindow: 128e3,
+				maxOutputTokens: 128e3
+			},
+			{
+				name: "gemma3:27b",
+				contextWindow: 128e3,
+				maxOutputTokens: 128e3
+			}
+		]
+	}
+];
+
+//#endregion
+//#region src/schemas/message-part.ts
+const basePartSchema = z.object({ id: z.string() });
+const textPartSchema = basePartSchema.extend({
+	type: z.literal("textPart"),
+	text: z.string()
+});
+const imageUrlPartSchema = basePartSchema.extend({
+	type: z.literal("imageUrlPart"),
+	url: z.url(),
+	mimeType: z.string()
+});
+const imageInlinePartSchema = basePartSchema.extend({
+	type: z.literal("imageInlinePart"),
+	encodedData: z.string(),
+	mimeType: z.string()
+});
+const imageBinaryPartSchema = basePartSchema.extend({
+	type: z.literal("imageBinaryPart"),
+	data: z.string(),
+	mimeType: z.string()
+});
+const fileUrlPartSchema = basePartSchema.extend({
+	type: z.literal("fileUrlPart"),
+	url: z.string().url(),
+	mimeType: z.string()
+});
+const fileInlinePartSchema = basePartSchema.extend({
+	type: z.literal("fileInlinePart"),
+	encodedData: z.string(),
+	mimeType: z.string()
+});
+const fileBinaryPartSchema = basePartSchema.extend({
+	type: z.literal("fileBinaryPart"),
+	data: z.string(),
+	mimeType: z.string()
+});
+const toolCallPartSchema = basePartSchema.extend({
+	type: z.literal("toolCallPart"),
+	toolCallId: z.string(),
+	toolName: z.string(),
+	args: z.record(z.string(), z.unknown())
+});
+const thinkingPartSchema = basePartSchema.extend({
+	type: z.literal("thinkingPart"),
+	thinking: z.string(),
+	signature: z.string().optional()
+});
+const toolResultPartSchema = basePartSchema.extend({
+	type: z.literal("toolResultPart"),
+	toolCallId: z.string(),
+	toolName: z.string(),
+	contents: z.array(z.union([
+		textPartSchema,
+		imageInlinePartSchema,
+		fileInlinePartSchema
+	])),
+	isError: z.boolean().optional()
+});
+const messagePartSchema = z.discriminatedUnion("type", [
+	textPartSchema,
+	imageUrlPartSchema,
+	imageInlinePartSchema,
+	imageBinaryPartSchema,
+	fileUrlPartSchema,
+	fileInlinePartSchema,
+	fileBinaryPartSchema,
+	toolCallPartSchema,
+	toolResultPartSchema,
+	thinkingPartSchema
+]);
+
+//#endregion
+//#region src/schemas/activity.ts
+const baseActivitySchema = z.object({
+	id: z.string(),
+	expertKey: z.string(),
+	runId: z.string(),
+	previousActivityId: z.string().optional(),
+	delegatedBy: z.object({
+		expertKey: z.string(),
+		runId: z.string()
+	}).optional(),
+	reasoning: z.string().optional()
+});
+const queryActivitySchema = baseActivitySchema.extend({
+	type: z.literal("query"),
+	text: z.string()
+});
+const retryActivitySchema = baseActivitySchema.extend({
+	type: z.literal("retry"),
+	error: z.string(),
+	message: z.string()
+});
+const completeActivitySchema = baseActivitySchema.extend({
+	type: z.literal("complete"),
+	text: z.string()
+});
+const errorActivitySchema = baseActivitySchema.extend({
+	type: z.literal("error"),
+	error: z.string().optional(),
+	errorName: z.string().optional(),
+	isRetryable: z.boolean().optional()
+});
+const attemptCompletionActivitySchema = baseActivitySchema.extend({
+	type: z.literal("attemptCompletion"),
+	remainingTodos: z.array(z.object({
+		id: z.number(),
+		title: z.string(),
+		completed: z.boolean()
+	})).optional(),
+	error: z.string().optional()
+});
+const todoActivitySchema = baseActivitySchema.extend({
+	type: z.literal("todo"),
+	newTodos: z.array(z.string()).optional(),
+	completedTodos: z.array(z.number()).optional(),
+	todos: z.array(z.object({
+		id: z.number(),
+		title: z.string(),
+		completed: z.boolean()
+	})),
+	error: z.string().optional()
+});
+const clearTodoActivitySchema = baseActivitySchema.extend({
+	type: z.literal("clearTodo"),
+	error: z.string().optional()
+});
+const readImageFileActivitySchema = baseActivitySchema.extend({
+	type: z.literal("readImageFile"),
+	path: z.string(),
+	mimeType: z.string().optional(),
+	size: z.number().optional(),
+	error: z.string().optional()
+});
+const readPdfFileActivitySchema = baseActivitySchema.extend({
+	type: z.literal("readPdfFile"),
+	path: z.string(),
+	mimeType: z.string().optional(),
+	size: z.number().optional(),
+	error: z.string().optional()
+});
+const readTextFileActivitySchema = baseActivitySchema.extend({
+	type: z.literal("readTextFile"),
+	path: z.string(),
+	content: z.string().optional(),
+	from: z.number().optional(),
+	to: z.number().optional(),
+	error: z.string().optional()
+});
+const editTextFileActivitySchema = baseActivitySchema.extend({
+	type: z.literal("editTextFile"),
+	path: z.string(),
+	newText: z.string(),
+	oldText: z.string(),
+	error: z.string().optional()
+});
+const writeTextFileActivitySchema = baseActivitySchema.extend({
+	type: z.literal("writeTextFile"),
+	path: z.string(),
+	text: z.string(),
+	error: z.string().optional()
+});
+const execActivitySchema = baseActivitySchema.extend({
+	type: z.literal("exec"),
+	command: z.string(),
+	args: z.array(z.string()),
+	cwd: z.string(),
+	output: z.string().optional(),
+	error: z.string().optional(),
+	stdout: z.string().optional(),
+	stderr: z.string().optional()
+});
+const delegateActivitySchema = baseActivitySchema.extend({
+	type: z.literal("delegate"),
+	delegateExpertKey: z.string(),
+	query: z.string()
+});
+const delegationCompleteActivitySchema = baseActivitySchema.extend({
+	type: z.literal("delegationComplete"),
+	count: z.number()
+});
+const interactiveToolActivitySchema = baseActivitySchema.extend({
+	type: z.literal("interactiveTool"),
+	skillName: z.string(),
+	toolName: z.string(),
+	args: z.record(z.string(), z.unknown())
+});
+const generalToolActivitySchema = baseActivitySchema.extend({
+	type: z.literal("generalTool"),
+	skillName: z.string(),
+	toolName: z.string(),
+	args: z.record(z.string(), z.unknown()),
+	result: z.array(messagePartSchema).optional(),
+	error: z.string().optional()
+});
+const addSkillActivitySchema = baseActivitySchema.extend({
+	type: z.literal("addSkill"),
+	name: z.string(),
+	skillType: z.string(),
+	tools: z.array(z.string()).optional(),
+	error: z.string().optional()
+});
+const removeSkillActivitySchema = baseActivitySchema.extend({
+	type: z.literal("removeSkill"),
+	skillName: z.string(),
+	error: z.string().optional()
+});
+const addDelegateActivitySchema = baseActivitySchema.extend({
+	type: z.literal("addDelegate"),
+	targetExpertKey: z.string(),
+	delegateToolName: z.string().optional(),
+	error: z.string().optional()
+});
+const removeDelegateActivitySchema = baseActivitySchema.extend({
+	type: z.literal("removeDelegate"),
+	expertName: z.string(),
+	error: z.string().optional()
+});
+const createExpertActivitySchema = baseActivitySchema.extend({
+	type: z.literal("createExpert"),
+	targetKey: z.string(),
+	description: z.string().optional(),
+	resultExpertKey: z.string().optional(),
+	error: z.string().optional()
+});
+const activitySchema = z.discriminatedUnion("type", [
+	queryActivitySchema,
+	retryActivitySchema,
+	completeActivitySchema,
+	errorActivitySchema,
+	attemptCompletionActivitySchema,
+	todoActivitySchema,
+	clearTodoActivitySchema,
+	readImageFileActivitySchema,
+	readPdfFileActivitySchema,
+	readTextFileActivitySchema,
+	editTextFileActivitySchema,
+	writeTextFileActivitySchema,
+	execActivitySchema,
+	delegateActivitySchema,
+	delegationCompleteActivitySchema,
+	interactiveToolActivitySchema,
+	generalToolActivitySchema,
+	addSkillActivitySchema,
+	removeSkillActivitySchema,
+	addDelegateActivitySchema,
+	removeDelegateActivitySchema,
+	createExpertActivitySchema
+]);
+const parallelActivitiesGroupSchema = z.object({
+	type: z.literal("parallelGroup"),
+	id: z.string(),
+	expertKey: z.string(),
+	runId: z.string(),
+	reasoning: z.string().optional(),
+	activities: z.array(activitySchema)
+});
+const activityOrGroupSchema = z.union([activitySchema, parallelActivitiesGroupSchema]);
+
+//#endregion
+//#region src/schemas/message.ts
+const baseMessageSchema = z.object({ id: z.string() });
+const instructionMessageSchema = baseMessageSchema.extend({
+	type: z.literal("instructionMessage"),
+	contents: z.array(textPartSchema),
+	cache: z.boolean().optional()
+});
+const userMessageSchema = baseMessageSchema.extend({
+	type: z.literal("userMessage"),
+	contents: z.array(z.union([
+		textPartSchema,
+		imageUrlPartSchema,
+		imageInlinePartSchema,
+		imageBinaryPartSchema,
+		fileUrlPartSchema,
+		fileInlinePartSchema,
+		fileBinaryPartSchema
+	])),
+	cache: z.boolean().optional()
+});
+const expertMessageSchema = baseMessageSchema.extend({
+	type: z.literal("expertMessage"),
+	contents: z.array(z.union([
+		textPartSchema,
+		toolCallPartSchema,
+		thinkingPartSchema
+	])),
+	cache: z.boolean().optional()
+});
+const toolMessageSchema = baseMessageSchema.extend({
+	type: z.literal("toolMessage"),
+	contents: z.array(toolResultPartSchema),
+	cache: z.boolean().optional()
+});
+const messageSchema = z.union([
+	instructionMessageSchema,
+	userMessageSchema,
+	expertMessageSchema,
+	toolMessageSchema
+]);
+
+//#endregion
+//#region src/schemas/tool-call.ts
+const toolCallSchema = z.object({
+	id: z.string().min(1).max(255),
+	skillName: z.string().min(1).max(maxSkillNameLength),
+	toolName: z.string().min(1).max(maxSkillToolNameLength),
+	args: z.record(z.string().min(1), z.unknown())
+});
+
+//#endregion
+//#region src/schemas/tool-result.ts
+const toolResultSchema = z.object({
+	id: z.string().min(1).max(255),
+	skillName: z.string().min(1).max(maxSkillNameLength),
+	toolName: z.string().min(1).max(maxSkillToolNameLength),
+	result: z.array(messagePartSchema)
+});
+
+//#endregion
+//#region src/schemas/usage.ts
+const usageSchema = z.object({
+	inputTokens: z.number(),
+	outputTokens: z.number(),
+	reasoningTokens: z.number(),
+	totalTokens: z.number(),
+	cachedInputTokens: z.number()
+});
+
+//#endregion
+//#region src/schemas/checkpoint.ts
+const checkpointStatusSchema = z.enum([
+	"init",
+	"proceeding",
+	"completed",
+	"stoppedByInteractiveTool",
+	"stoppedByDelegate",
+	"stoppedByError",
+	"stoppedByCancellation"
+]);
+const delegationTargetSchema = z.object({
+	expert: z.object({
+		key: z.string(),
+		name: z.string(),
+		version: z.string()
+	}),
+	toolCallId: z.string(),
+	toolName: z.string(),
+	query: z.string()
+});
+const checkpointSchema = z.object({
+	id: z.string(),
+	jobId: z.string(),
+	runId: z.string(),
+	status: checkpointStatusSchema,
+	stepNumber: z.number(),
+	messages: z.array(messageSchema),
+	expert: z.object({
+		key: z.string(),
+		name: z.string(),
+		version: z.string()
+	}),
+	delegateTo: z.array(delegationTargetSchema).optional(),
+	delegatedBy: z.object({
+		expert: z.object({
+			key: z.string(),
+			name: z.string(),
+			version: z.string()
+		}),
+		toolCallId: z.string(),
+		toolName: z.string(),
+		checkpointId: z.string(),
+		runId: z.string()
+	}).optional(),
+	usage: usageSchema,
+	contextWindow: z.number().optional(),
+	contextWindowUsage: z.number().optional(),
+	pendingToolCalls: z.array(toolCallSchema).optional(),
+	partialToolResults: z.array(toolResultSchema).optional(),
+	metadata: z.object({}).passthrough().optional(),
+	error: z.object({
+		name: z.string(),
+		message: z.string(),
+		statusCode: z.number().optional(),
+		isRetryable: z.boolean()
+	}).optional(),
+	retryCount: z.number().optional()
+});
+
+//#endregion
+//#region src/utils/expert-type.ts
+function getExpertType(expertName) {
+	return expertName.startsWith("@") ? "delegate" : "coordinator";
+}
+function isCoordinatorExpert(expertName) {
+	return getExpertType(expertName) === "coordinator";
+}
+function isDelegateExpert(expertName) {
+	return getExpertType(expertName) === "delegate";
+}
+/**
+* Returns the scope of an expert.
+* Handles both bare names and versioned keys (with @version/@tag suffix).
+* - Coordinator "game-producer" -> "game-producer"
+* - Coordinator "game-producer@1.0.0" -> "game-producer"
+* - Delegate "@game-producer/designer" -> "game-producer"
+* - Delegate "@game-producer/designer@1.0.0" -> "game-producer"
+*/
+function getExpertScope(expertName) {
+	if (isDelegateExpert(expertName)) {
+		const withoutAt = expertName.slice(1);
+		const slashIndex = withoutAt.indexOf("/");
+		return slashIndex === -1 ? withoutAt : withoutAt.slice(0, slashIndex);
+	}
+	const atIndex = expertName.indexOf("@");
+	return atIndex === -1 ? expertName : expertName.slice(0, atIndex);
+}
+/**
+* Returns the short name of an expert.
+* Handles both bare names and versioned keys (with @version/@tag suffix).
+* - Coordinator "game-producer" -> "game-producer"
+* - Coordinator "game-producer@1.0.0" -> "game-producer"
+* - Delegate "@game-producer/designer" -> "designer"
+* - Delegate "@game-producer/designer@1.0.0" -> "designer"
+*/
+function getExpertShortName(expertName) {
+	if (isDelegateExpert(expertName)) {
+		const slashIndex = expertName.indexOf("/");
+		const shortName = slashIndex === -1 ? expertName : expertName.slice(slashIndex + 1);
+		const atIndex = shortName.indexOf("@");
+		return atIndex === -1 ? shortName : shortName.slice(0, atIndex);
+	}
+	const atIndex = expertName.indexOf("@");
+	return atIndex === -1 ? expertName : expertName.slice(0, atIndex);
+}
+/**
+* Validates whether a delegation from source to target is allowed.
+* Returns null if valid, an error message string if invalid.
+*
+* Rules:
+* - No self-delegation
+* - If target is a delegate (@scope/name), source must be in the same scope
+* - A delegate cannot delegate to its own coordinator
+*/
+function validateDelegation(source, target) {
+	if (source === target) return `Expert "${source}" cannot delegate to itself`;
+	const sourceScope = getExpertScope(source);
+	if (isDelegateExpert(target)) {
+		if (sourceScope !== getExpertScope(target)) return `Expert "${source}" cannot delegate to out-of-scope delegate "${target}"`;
+	}
+	if (isDelegateExpert(source) && isCoordinatorExpert(target) && getExpertScope(target) === sourceScope) return `Delegate "${source}" cannot delegate to its own coordinator "${target}"`;
+	return null;
+}
+/**
+* Validates all delegations for an expert.
+* Returns an array of error messages (empty if all valid).
+*/
+function validateAllDelegations(expertName, delegates) {
+	const errors = [];
+	for (const delegate of delegates) {
+		const error = validateDelegation(expertName, delegate);
+		if (error) errors.push(error);
+	}
+	return errors;
+}
+
+//#endregion
+//#region src/schemas/provider-tools.ts
+const anthropicProviderToolNameSchema = z.enum([
+	"webSearch",
+	"webFetch",
+	"codeExecution"
+]);
+const builtinAnthropicSkillSchema = z.object({
+	type: z.literal("builtin"),
+	skillId: z.enum([
+		"pdf",
+		"docx",
+		"pptx",
+		"xlsx"
+	])
+});
+const customAnthropicSkillSchema = z.object({
+	type: z.literal("custom"),
+	name: z.string().min(1),
+	definition: z.string().min(1)
+});
+const anthropicProviderSkillSchema = z.discriminatedUnion("type", [builtinAnthropicSkillSchema, customAnthropicSkillSchema]);
+const openaiProviderToolNameSchema = z.enum([
+	"webSearch",
+	"fileSearch",
+	"codeInterpreter",
+	"imageGeneration"
+]);
+const googleProviderToolNameSchema = z.enum([
+	"googleSearch",
+	"codeExecution",
+	"urlContext",
+	"fileSearch",
+	"googleMaps"
+]);
+const azureOpenAIProviderToolNameSchema = z.enum([
+	"webSearchPreview",
+	"fileSearch",
+	"codeInterpreter",
+	"imageGeneration"
+]);
+const vertexProviderToolNameSchema = z.enum([
+	"codeExecution",
+	"urlContext",
+	"googleSearch",
+	"enterpriseWebSearch",
+	"googleMaps"
+]);
+const webSearchOptionsSchema = z.object({
+	maxUses: z.number().int().positive().optional(),
+	allowedDomains: z.array(z.string()).optional()
+});
+const webFetchOptionsSchema = z.object({ maxUses: z.number().int().positive().optional() });
+const fileSearchOptionsSchema = z.object({
+	vectorStoreIds: z.array(z.string()).optional(),
+	maxNumResults: z.number().int().positive().optional()
+});
+const providerToolOptionsSchema = z.object({
+	webSearch: webSearchOptionsSchema.optional(),
+	webFetch: webFetchOptionsSchema.optional(),
+	fileSearch: fileSearchOptionsSchema.optional()
+}).optional();
+
+//#endregion
+//#region src/schemas/runtime-version.ts
+const runtimeVersionSchema = z.string().regex(/^v\d+\.\d+$/, "Runtime version must be in format \"vX.Y\" (e.g., \"v1.0\")").transform((v) => v);
+
+//#endregion
+//#region src/schemas/skill.ts
+function isPrivateOrLocalIP(hostname) {
+	if (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" || hostname === "0.0.0.0") return true;
+	const ipv4Match = hostname.match(/^(\d+)\.(\d+)\.(\d+)\.(\d+)$/);
+	if (ipv4Match) {
+		const a = Number(ipv4Match[1]);
+		const b = Number(ipv4Match[2]);
+		if (a === 10) return true;
+		if (a === 172 && b >= 16 && b <= 31) return true;
+		if (a === 192 && b === 168) return true;
+		if (a === 169 && b === 254) return true;
+		if (a === 127) return true;
+	}
+	if (hostname.includes(":")) {
+		if (hostname.startsWith("fe80:") || hostname.startsWith("fc") || hostname.startsWith("fd")) return true;
+	}
+	if (hostname.startsWith("::ffff:")) {
+		if (isPrivateOrLocalIP(hostname.slice(7))) return true;
+	}
+	return false;
+}
+const sseEndpointSchema$1 = z.string().url().refine((url) => {
+	try {
+		const parsed = new URL(url);
+		if (parsed.protocol !== "https:") return false;
+		if (isPrivateOrLocalIP(parsed.hostname)) return false;
+		return true;
+	} catch {
+		return false;
+	}
+}, { message: "Endpoint must be a public HTTPS URL" });
+const mcpStdioSkillSchema = z.object({
+	type: z.literal("mcpStdioSkill"),
+	name: z.string(),
+	description: z.string().optional(),
+	rule: z.string().optional(),
+	pick: z.array(z.string()).optional().default([]),
+	omit: z.array(z.string()).optional().default([]),
+	command: z.string(),
+	packageName: z.string().optional(),
+	args: z.array(z.string()).optional().default([]),
+	requiredEnv: z.array(z.string()).optional().default([])
+});
+const mcpSseSkillSchema = z.object({
+	type: z.literal("mcpSseSkill"),
+	name: z.string(),
+	description: z.string().optional(),
+	rule: z.string().optional(),
+	pick: z.array(z.string()).optional().default([]),
+	omit: z.array(z.string()).optional().default([]),
+	endpoint: sseEndpointSchema$1
+});
+const interactiveToolSchema = z.object({
+	name: z.string(),
+	description: z.string().optional(),
+	inputJsonSchema: z.string()
+});
+const interactiveSkillSchema = z.object({
+	type: z.literal("interactiveSkill"),
+	name: z.string(),
+	description: z.string().optional(),
+	rule: z.string().optional(),
+	tools: z.record(z.string(), interactiveToolSchema.omit({ name: true })).transform((tools) => {
+		return Object.fromEntries(Object.entries(tools).map(([key, toolWithoutName]) => [key, interactiveToolSchema.parse({
+			...toolWithoutName,
+			name: key
+		})]));
+	})
+});
+const skillSchema = z.discriminatedUnion("type", [
+	mcpStdioSkillSchema,
+	mcpSseSkillSchema,
+	interactiveSkillSchema
+]);
+
+//#endregion
+//#region src/schemas/expert.ts
+/**
+* Base object schema for Expert. Use this for `.omit()` / `.pick()` operations.
+* For parsing with delegation validation, use `expertSchema` instead.
+*/
+const expertBaseSchema = z.object({
+	key: z.string().regex(expertKeyRegex).min(1),
+	name: z.string().regex(expertNameRegex).min(1).max(maxExpertNameLength),
+	version: z.string().regex(expertVersionRegex),
+	description: z.string().max(1024 * 2).optional(),
+	instruction: z.string().min(1).max(1024 * 20),
+	skills: z.record(z.string(), z.discriminatedUnion("type", [
+		mcpStdioSkillSchema.omit({ name: true }),
+		mcpSseSkillSchema.omit({ name: true }),
+		interactiveSkillSchema.omit({ name: true })
+	])).optional().default({ "@perstack/base": {
+		type: "mcpStdioSkill",
+		description: "Base skill",
+		command: "npx",
+		args: ["-y", "@perstack/base"],
+		pick: [],
+		omit: [],
+		requiredEnv: []
+	} }).transform((skills) => {
+		return Object.fromEntries(Object.entries(skills).map(([key, skillWithoutName]) => [key, z.discriminatedUnion("type", [
+			mcpStdioSkillSchema,
+			mcpSseSkillSchema,
+			interactiveSkillSchema
+		]).parse({
+			...skillWithoutName,
+			name: key
+		})]));
+	}),
+	delegates: z.array(z.string().regex(expertKeyRegex).min(1)).optional().default([]),
+	tags: z.array(z.string().regex(tagNameRegex).min(1)).optional().default([]),
+	minRuntimeVersion: runtimeVersionSchema.default("v1.0"),
+	providerTools: z.array(z.string()).optional(),
+	providerSkills: z.array(anthropicProviderSkillSchema).optional(),
+	providerToolOptions: providerToolOptionsSchema
+});
+/**
+* Expert schema with delegation rule validation.
+* Rejects self-delegation, out-of-scope delegates, and delegate-to-own-coordinator.
+*/
+const expertSchema = expertBaseSchema.superRefine((data, ctx) => {
+	const errors = validateAllDelegations(data.key, data.delegates);
+	for (const error of errors) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		message: error,
+		path: ["delegates"]
+	});
+});
+
+//#endregion
+//#region src/schemas/job.ts
+const jobStatusSchema = z.enum([
+	"running",
+	"completed",
+	"stoppedByInteractiveTool",
+	"stoppedByError",
+	"stoppedByCancellation"
+]);
+const jobSchema = z.object({
+	id: z.string(),
+	status: jobStatusSchema,
+	coordinatorExpertKey: z.string(),
+	runtimeVersion: runtimeVersionSchema,
+	totalSteps: z.number(),
+	usage: usageSchema,
+	startedAt: z.number(),
+	finishedAt: z.number().optional()
+});
+
+//#endregion
+//#region src/schemas/lockfile.ts
+const lockfileToolDefinitionSchema = z.object({
+	skillName: z.string(),
+	name: z.string(),
+	description: z.string().optional(),
+	inputSchema: z.record(z.string(), z.unknown())
+});
+const lockfileExpertSchema = z.object({
+	key: z.string(),
+	name: z.string(),
+	version: z.string(),
+	description: z.string().optional(),
+	instruction: z.string(),
+	skills: z.record(z.string(), skillSchema),
+	delegates: z.array(z.string()),
+	tags: z.array(z.string()),
+	toolDefinitions: z.array(lockfileToolDefinitionSchema)
+});
+const lockfileSchema = z.object({
+	version: z.literal("1"),
+	generatedAt: z.number(),
+	configPath: z.string(),
+	experts: z.record(z.string(), lockfileExpertSchema)
+});
+
+//#endregion
+//#region src/schemas/provider-config.ts
+const headersSchema = z.record(z.string(), z.string()).optional();
+const providerNameSchema = z.enum([
+	"anthropic",
+	"google",
+	"openai",
+	"ollama",
+	"azure-openai",
+	"amazon-bedrock",
+	"google-vertex",
+	"deepseek"
+]);
+const anthropicProviderConfigSchema = z.object({
+	providerName: z.literal(providerNameSchema.enum.anthropic),
+	apiKey: z.string(),
+	baseUrl: z.string().optional(),
+	headers: headersSchema
+});
+const googleGenerativeAiProviderConfigSchema = z.object({
+	providerName: z.literal(providerNameSchema.enum.google),
+	apiKey: z.string(),
+	baseUrl: z.string().optional(),
+	headers: headersSchema
+});
+const openAiProviderConfigSchema = z.object({
+	providerName: z.literal(providerNameSchema.enum.openai),
+	apiKey: z.string(),
+	baseUrl: z.string().optional(),
+	organization: z.string().optional(),
+	project: z.string().optional(),
+	name: z.string().optional(),
+	headers: headersSchema
+});
+const ollamaProviderConfigSchema = z.object({
+	providerName: z.literal(providerNameSchema.enum.ollama),
+	baseUrl: z.string().optional(),
+	headers: headersSchema
+});
+const azureOpenAiProviderConfigSchema = z.object({
+	providerName: z.literal(providerNameSchema.enum["azure-openai"]),
+	apiKey: z.string(),
+	resourceName: z.string().optional(),
+	apiVersion: z.string().optional(),
+	baseUrl: z.string().optional(),
+	headers: headersSchema,
+	useDeploymentBasedUrls: z.boolean().optional()
+});
+const amazonBedrockProviderConfigSchema = z.object({
+	providerName: z.literal(providerNameSchema.enum["amazon-bedrock"]),
+	accessKeyId: z.string(),
+	secretAccessKey: z.string(),
+	region: z.string(),
+	sessionToken: z.string().optional()
+});
+const googleVertexProviderConfigSchema = z.object({
+	providerName: z.literal(providerNameSchema.enum["google-vertex"]),
+	project: z.string().optional(),
+	location: z.string().optional(),
+	baseUrl: z.string().optional(),
+	headers: headersSchema
+});
+const deepseekProviderConfigSchema = z.object({
+	providerName: z.literal(providerNameSchema.enum.deepseek),
+	apiKey: z.string(),
+	baseUrl: z.string().optional(),
+	headers: headersSchema
+});
+const providerConfigSchema = z.discriminatedUnion("providerName", [
+	anthropicProviderConfigSchema,
+	googleGenerativeAiProviderConfigSchema,
+	openAiProviderConfigSchema,
+	ollamaProviderConfigSchema,
+	azureOpenAiProviderConfigSchema,
+	amazonBedrockProviderConfigSchema,
+	googleVertexProviderConfigSchema,
+	deepseekProviderConfigSchema
+]);
+
+//#endregion
+//#region src/schemas/perstack-toml.ts
+/** Default reasoning budget - enables extended thinking by default */
+const defaultReasoningBudget = "low";
+const reasoningBudgetSchema = z.union([z.enum([
+	"none",
+	"minimal",
+	"low",
+	"medium",
+	"high"
+]), z.number().int().nonnegative()]);
+const domainPatternRegex = /^(\*\.)?[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)*$/;
+const punycodeRegex = /(?:^|\.)(xn--)/i;
+const domainPatternSchema = z.string().regex(domainPatternRegex, { message: "Invalid domain pattern. Use exact domain (example.com) or wildcard prefix (*.example.com)" }).refine((domain) => !punycodeRegex.test(domain), { message: "Punycode domains (xn--) are not allowed to prevent homograph attacks. Use ASCII domains only." });
+const sseEndpointSchema = z.string().url().refine((url) => {
+	try {
+		const parsed = new URL(url);
+		if (parsed.protocol !== "https:") return false;
+		if (isPrivateOrLocalIP(parsed.hostname)) return false;
+		return true;
+	} catch {
+		return false;
+	}
+}, { message: "SSE endpoint must be a public HTTPS URL" });
+const httpsUrlSchema = z.string().url().refine((url) => url.startsWith("https://"), { message: "URL must use HTTPS" });
+const anthropicSettingSchema = z.object({
+	baseUrl: httpsUrlSchema.optional(),
+	headers: headersSchema
+});
+const googleSettingSchema = z.object({
+	baseUrl: httpsUrlSchema.optional(),
+	headers: headersSchema
+});
+const openAiSettingSchema = z.object({
+	baseUrl: httpsUrlSchema.optional(),
+	organization: z.string().optional(),
+	project: z.string().optional(),
+	name: z.string().optional(),
+	headers: headersSchema
+});
+const ollamaSettingSchema = z.object({
+	baseUrl: z.string().optional(),
+	headers: headersSchema
+});
+const azureOpenAiSettingSchema = z.object({
+	resourceName: z.string().optional(),
+	apiVersion: z.string().optional(),
+	baseUrl: httpsUrlSchema.optional(),
+	headers: headersSchema,
+	useDeploymentBasedUrls: z.boolean().optional()
+});
+const amazonBedrockSettingSchema = z.object({ region: z.string().optional() });
+const googleVertexSettingSchema = z.object({
+	project: z.string().optional(),
+	location: z.string().optional(),
+	baseUrl: httpsUrlSchema.optional(),
+	headers: headersSchema
+});
+const deepseekSettingSchema = z.object({
+	baseUrl: httpsUrlSchema.optional(),
+	headers: headersSchema
+});
+const providerTableSchema = z.discriminatedUnion("providerName", [
+	z.object({
+		providerName: z.literal("anthropic"),
+		setting: anthropicSettingSchema.optional()
+	}),
+	z.object({
+		providerName: z.literal("google"),
+		setting: googleSettingSchema.optional()
+	}),
+	z.object({
+		providerName: z.literal("openai"),
+		setting: openAiSettingSchema.optional()
+	}),
+	z.object({
+		providerName: z.literal("ollama"),
+		setting: ollamaSettingSchema.optional()
+	}),
+	z.object({
+		providerName: z.literal("azure-openai"),
+		setting: azureOpenAiSettingSchema.optional()
+	}),
+	z.object({
+		providerName: z.literal("amazon-bedrock"),
+		setting: amazonBedrockSettingSchema.optional()
+	}),
+	z.object({
+		providerName: z.literal("google-vertex"),
+		setting: googleVertexSettingSchema.optional()
+	}),
+	z.object({
+		providerName: z.literal("deepseek"),
+		setting: deepseekSettingSchema.optional()
+	})
+]);
+const perstackConfigSchema = z.object({
+	provider: providerTableSchema.optional(),
+	model: z.string().optional(),
+	reasoningBudget: reasoningBudgetSchema.optional(),
+	maxRetries: z.number().optional(),
+	timeout: z.number().optional(),
+	experts: z.record(z.string(), z.object({
+		version: z.string().optional(),
+		minRuntimeVersion: runtimeVersionSchema.optional(),
+		description: z.string().optional(),
+		instruction: z.string(),
+		skills: z.record(z.string(), z.discriminatedUnion("type", [
+			z.object({
+				type: z.literal("mcpStdioSkill"),
+				description: z.string().optional(),
+				rule: z.string().optional(),
+				pick: z.array(z.string()).optional(),
+				omit: z.array(z.string()).optional(),
+				command: z.string(),
+				packageName: z.string().optional(),
+				args: z.array(z.string()).optional(),
+				requiredEnv: z.array(z.string()).optional(),
+				allowedDomains: z.array(domainPatternSchema).optional()
+			}),
+			z.object({
+				type: z.literal("mcpSseSkill"),
+				description: z.string().optional(),
+				rule: z.string().optional(),
+				pick: z.array(z.string()).optional(),
+				omit: z.array(z.string()).optional(),
+				endpoint: sseEndpointSchema,
+				allowedDomains: z.array(domainPatternSchema).optional()
+			}),
+			z.object({
+				type: z.literal("interactiveSkill"),
+				description: z.string().optional(),
+				rule: z.string().optional(),
+				tools: z.record(z.string(), z.object({
+					description: z.string().optional(),
+					inputJsonSchema: z.string()
+				}))
+			})
+		])).optional(),
+		delegates: z.array(z.string()).optional(),
+		tags: z.array(z.string()).optional(),
+		providerTools: z.array(z.string()).optional(),
+		providerSkills: z.array(anthropicProviderSkillSchema).optional(),
+		providerToolOptions: providerToolOptionsSchema
+	})).optional(),
+	perstackApiBaseUrl: z.url().refine((url) => url.startsWith("https://"), { message: "perstackApiBaseUrl must use HTTPS" }).optional(),
+	perstackBaseSkillCommand: z.array(z.string()).optional(),
+	envPath: z.array(z.string()).optional()
+});
+
+//#endregion
+//#region src/schemas/run-command.ts
+const commandOptionsSchema = z.object({
+	config: z.string().optional(),
+	provider: providerNameSchema.optional(),
+	model: z.string().optional(),
+	reasoningBudget: z.string().optional().transform((value) => {
+		if (value === void 0) return void 0;
+		if ([
+			"none",
+			"minimal",
+			"low",
+			"medium",
+			"high"
+		].includes(value)) return value;
+		const parsedValue = Number.parseInt(value, 10);
+		if (Number.isNaN(parsedValue)) return void 0;
+		return parsedValue;
+	}).pipe(reasoningBudgetSchema.optional()),
+	maxRetries: z.string().optional().transform((value) => {
+		if (value === void 0) return void 0;
+		const parsedValue = Number.parseInt(value, 10);
+		if (Number.isNaN(parsedValue)) return void 0;
+		return parsedValue;
+	}),
+	timeout: z.string().optional().transform((value) => {
+		if (value === void 0) return void 0;
+		const parsedValue = Number.parseInt(value, 10);
+		if (Number.isNaN(parsedValue)) return void 0;
+		return parsedValue;
+	}),
+	jobId: z.string().optional(),
+	runId: z.string().optional(),
+	envPath: z.array(z.string()).optional().transform((value) => value && value.length > 0 ? value : void 0),
+	verbose: z.boolean().optional(),
+	continue: z.boolean().optional(),
+	continueJob: z.string().optional(),
+	resumeFrom: z.string().optional(),
+	interactiveToolCallResult: z.boolean().optional(),
+	filter: z.string().optional().transform((value) => {
+		if (value === void 0) return void 0;
+		return value.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+	}).pipe(z.array(z.string()).optional())
+});
+const runCommandInputSchema = z.object({
+	expertKey: z.string(),
+	query: z.string(),
+	options: commandOptionsSchema
+});
+const startCommandInputSchema = z.object({
+	expertKey: z.string().optional(),
+	query: z.string().optional(),
+	options: commandOptionsSchema
+});
+
+//#endregion
+//#region src/schemas/runtime.ts
+/** Parse an expert key into its components */
+function parseExpertKey(expertKey) {
+	const match = expertKey.match(expertKeyRegex);
+	if (!match) throw new PerstackError(`Invalid expert key format: ${expertKey}`);
+	const [key, name, version, tag] = match;
+	if (!name) throw new PerstackError(`Invalid expert key format: ${expertKey}`);
+	return {
+		key,
+		name,
+		version,
+		tag
+	};
+}
+const runSettingSchema = z.object({
+	model: z.string(),
+	providerConfig: providerConfigSchema,
+	jobId: z.string(),
+	runId: z.string(),
+	expertKey: z.string().min(1).regex(expertKeyRegex),
+	input: z.object({
+		text: z.string().optional(),
+		interactiveToolCallResult: z.object({
+			toolCallId: z.string(),
+			toolName: z.string(),
+			skillName: z.string(),
+			text: z.string()
+		}).optional()
+	}),
+	experts: z.record(z.string(), expertSchema),
+	reasoningBudget: reasoningBudgetSchema.default(defaultReasoningBudget),
+	maxRetries: z.number().min(0),
+	timeout: z.number().min(0),
+	startedAt: z.number(),
+	updatedAt: z.number(),
+	perstackApiBaseUrl: z.string().url(),
+	perstackApiKey: z.string().optional(),
+	perstackBaseSkillCommand: z.array(z.string()).optional(),
+	env: z.record(z.string(), z.string()),
+	proxyUrl: z.string().optional(),
+	verbose: z.boolean().optional()
+});
+const runParamsSchema = z.object({
+	setting: z.object({
+		model: z.string(),
+		providerConfig: providerConfigSchema,
+		jobId: z.string().optional().default(() => createId()),
+		runId: z.string().optional().default(() => createId()),
+		expertKey: z.string().min(1).regex(expertKeyRegex),
+		input: z.object({
+			text: z.string().optional(),
+			interactiveToolCallResult: z.object({
+				toolCallId: z.string(),
+				toolName: z.string(),
+				skillName: z.string(),
+				text: z.string()
+			}).optional()
+		}),
+		experts: z.record(z.string().min(1).regex(expertKeyRegex), expertBaseSchema.omit({ key: true })).optional().default({}).transform((experts) => Object.fromEntries(Object.entries(experts).map(([key, expertWithoutKey]) => [key, expertSchema.parse({
+			...expertWithoutKey,
+			key
+		})]))),
+		reasoningBudget: reasoningBudgetSchema.optional().default(defaultReasoningBudget),
+		maxRetries: z.number().min(0).optional().default(defaultMaxRetries),
+		timeout: z.number().min(0).optional().default(defaultTimeout),
+		startedAt: z.number().optional().default(Date.now()),
+		updatedAt: z.number().optional().default(Date.now()),
+		perstackApiBaseUrl: z.url().optional().default(defaultPerstackApiBaseUrl),
+		perstackApiKey: z.string().optional(),
+		perstackBaseSkillCommand: z.array(z.string()).optional(),
+		env: z.record(z.string(), z.string()).optional().default({}),
+		proxyUrl: z.string().optional(),
+		verbose: z.boolean().optional()
+	}),
+	checkpoint: checkpointSchema.optional()
+});
+/** Factory function to create expert state events */
+function createEvent(type) {
+	return (setting, checkpoint, data) => {
+		return {
+			type,
+			id: createId(),
+			expertKey: checkpoint.expert.key,
+			timestamp: Date.now(),
+			jobId: setting.jobId,
+			runId: setting.runId,
+			stepNumber: checkpoint.stepNumber,
+			...data
+		};
+	};
+}
+/** Factory function to create streaming events */
+function createStreamingEvent(type, setting, checkpoint, data) {
+	return {
+		type,
+		id: createId(),
+		expertKey: checkpoint.expert.key,
+		timestamp: Date.now(),
+		jobId: setting.jobId,
+		runId: setting.runId,
+		stepNumber: checkpoint.stepNumber,
+		...data
+	};
+}
+const startRun = createEvent("startRun");
+const resumeFromStop = createEvent("resumeFromStop");
+const proceedToInteractiveTools = createEvent("proceedToInteractiveTools");
+const startGeneration = createEvent("startGeneration");
+const retry = createEvent("retry");
+const callTools = createEvent("callTools");
+const finishMcpTools = createEvent("finishMcpTools");
+const skipDelegates = createEvent("skipDelegates");
+const resolveToolResults = createEvent("resolveToolResults");
+const finishToolCall = createEvent("finishToolCall");
+const resumeToolCalls = createEvent("resumeToolCalls");
+const completeRun = createEvent("completeRun");
+const stopRunByInteractiveTool = createEvent("stopRunByInteractiveTool");
+const stopRunByDelegate = createEvent("stopRunByDelegate");
+const stopRunByError = createEvent("stopRunByError");
+const continueToNextStep = createEvent("continueToNextStep");
+/** Factory function to create runtime events */
+function createRuntimeEvent(type, jobId, runId, data) {
+	return {
+		type,
+		id: createId(),
+		timestamp: Date.now(),
+		jobId,
+		runId,
+		...data
+	};
+}
+/**
+* Valid expert state event types (state machine transitions)
+*/
+const EXPERT_STATE_EVENT_TYPES = new Set([
+	"startRun",
+	"resumeFromStop",
+	"proceedToInteractiveTools",
+	"startGeneration",
+	"retry",
+	"callTools",
+	"finishMcpTools",
+	"skipDelegates",
+	"resolveToolResults",
+	"finishToolCall",
+	"resumeToolCalls",
+	"continueToNextStep",
+	"stopRunByInteractiveTool",
+	"stopRunByDelegate",
+	"stopRunByError",
+	"completeRun"
+]);
+/**
+* Valid streaming event types
+*/
+const STREAMING_EVENT_TYPES = new Set([
+	"startStreamingReasoning",
+	"streamReasoning",
+	"completeStreamingReasoning",
+	"startStreamingRunResult",
+	"streamRunResult",
+	"completeStreamingRunResult"
+]);
+/**
+* Valid runtime event types (infrastructure-level events)
+*/
+const RUNTIME_EVENT_TYPES = new Set([
+	"initializeRuntime",
+	"skillStarting",
+	"skillConnected",
+	"skillStderr",
+	"skillDisconnected"
+]);
+/** Validate if a string is a valid RunEvent type (ExpertStateEvent or StreamingEvent) */
+function isValidEventType(type) {
+	return EXPERT_STATE_EVENT_TYPES.has(type) || STREAMING_EVENT_TYPES.has(type);
+}
+/** Validate if a string is a valid RuntimeEvent type */
+function isValidRuntimeEventType(type) {
+	return RUNTIME_EVENT_TYPES.has(type);
+}
+
+//#endregion
+//#region src/schemas/step.ts
+const stepSchema = z.object({
+	stepNumber: z.number(),
+	inputMessages: z.array(z.union([
+		instructionMessageSchema,
+		userMessageSchema,
+		toolMessageSchema
+	])).optional(),
+	newMessages: z.array(messageSchema),
+	toolCalls: z.array(toolCallSchema).optional(),
+	toolResults: z.array(toolResultSchema).optional(),
+	pendingToolCalls: z.array(toolCallSchema).optional(),
+	partialToolResults: z.array(toolResultSchema).optional(),
+	usage: usageSchema,
+	startedAt: z.number(),
+	finishedAt: z.number().optional()
+});
+
+//#endregion
+//#region src/utils/activity.ts
+const BASE_SKILL_PREFIX = "@perstack/base";
+/**
+* Extracts reasoning from Step.newMessages by finding thinkingParts.
+*/
+function extractReasoning(newMessages) {
+	const thinkingParts = [];
+	for (const message of newMessages) for (const content of message.contents) if (content.type === "thinkingPart") thinkingParts.push(content);
+	if (thinkingParts.length === 0) return void 0;
+	return thinkingParts.map((p) => p.thinking).join("\n\n");
+}
+/**
+* Wraps multiple activities into a ParallelActivitiesGroup when they share reasoning.
+* Single activities are returned as-is.
+*/
+function wrapInGroupIfParallel(activities, reasoning, expertKey, runId, stepNumber) {
+	if (activities.length <= 1) return activities;
+	const activitiesWithoutReasoning = activities.map((a) => {
+		const { reasoning: _, ...rest } = a;
+		return rest;
+	});
+	return [{
+		type: "parallelGroup",
+		id: `parallel-${runId}-step${stepNumber}`,
+		expertKey,
+		runId,
+		reasoning,
+		activities: activitiesWithoutReasoning
+	}];
+}
+/**
+* Computes activities from a checkpoint and step.
+* Returns an array of activities or activity groups, supporting parallel tool calls and delegations.
+* When multiple activities are produced from a single step, they are wrapped in a ParallelActivitiesGroup
+* with shared reasoning.
+*/
+function getActivities(params) {
+	const { checkpoint, step } = params;
+	const { status, delegateTo, runId, stepNumber } = checkpoint;
+	const expertKey = checkpoint.expert.key;
+	const reasoning = extractReasoning(step.newMessages);
+	let queryActivity;
+	if (stepNumber === 1 && step.inputMessages) {
+		const userMessage = step.inputMessages.find((m) => m.type === "userMessage");
+		if (userMessage) {
+			const textPart = userMessage.contents.find((c) => c.type === "textPart");
+			if (textPart && "text" in textPart) queryActivity = {
+				type: "query",
+				id: "",
+				expertKey,
+				runId,
+				text: textPart.text
+			};
+		}
+	}
+	const prependQuery = (result) => queryActivity ? [queryActivity, ...result] : result;
+	if (status === "stoppedByError") return prependQuery([createErrorActivity(checkpoint, reasoning)]);
+	if (status === "stoppedByDelegate") {
+		if (!delegateTo || delegateTo.length === 0) return prependQuery([createRetryActivity(step.newMessages, reasoning, "Delegate status but no delegation targets")]);
+		return prependQuery(wrapInGroupIfParallel(delegateTo.map((d) => createDelegateActivity(d, reasoning)), reasoning, expertKey, runId, stepNumber));
+	}
+	if (status === "stoppedByInteractiveTool") {
+		const toolCalls = step.toolCalls ?? [];
+		if (toolCalls.length === 0) return prependQuery([createRetryActivity(step.newMessages, reasoning)]);
+		return prependQuery(wrapInGroupIfParallel(toolCalls.map((tc) => createInteractiveToolActivity(tc.skillName, tc.toolName, tc, reasoning)), reasoning, expertKey, runId, stepNumber));
+	}
+	const toolCalls = step.toolCalls ?? [];
+	const toolResults = step.toolResults ?? [];
+	if (toolCalls.length === 0) {
+		if (status === "completed") return prependQuery([createCompleteActivity(step.newMessages, reasoning)]);
+		if (status === "proceeding" || status === "init") return prependQuery([]);
+		return prependQuery([createRetryActivity(step.newMessages, reasoning)]);
+	}
+	const toolActivities = [];
+	for (const toolCall of toolCalls) {
+		const toolResult = toolResults.find((tr) => tr.id === toolCall.id);
+		if (!toolResult) continue;
+		const { skillName, toolName } = toolCall;
+		if (skillName.startsWith(BASE_SKILL_PREFIX)) toolActivities.push(createBaseToolActivity(toolName, toolCall, toolResult, reasoning));
+		else toolActivities.push(createGeneralToolActivity(skillName, toolName, toolCall, toolResult, reasoning));
+	}
+	if (toolActivities.length === 0) {
+		if (status === "completed") return prependQuery([createCompleteActivity(step.newMessages, reasoning)]);
+		if (status === "proceeding" || status === "init") return prependQuery([]);
+		return prependQuery([createRetryActivity(step.newMessages, reasoning)]);
+	}
+	const result = wrapInGroupIfParallel(toolActivities, reasoning, expertKey, runId, stepNumber);
+	if (status === "completed") result.push(createCompleteActivity(step.newMessages, void 0));
+	return prependQuery(result);
+}
+function createCompleteActivity(newMessages, reasoning) {
+	return {
+		type: "complete",
+		id: "",
+		expertKey: "",
+		runId: "",
+		reasoning,
+		text: ([...newMessages].reverse().find((m) => m.type === "expertMessage")?.contents.find((c) => c.type === "textPart"))?.text ?? ""
+	};
+}
+function createDelegateActivity(delegate, reasoning) {
+	return {
+		type: "delegate",
+		id: "",
+		expertKey: "",
+		runId: "",
+		reasoning,
+		delegateExpertKey: delegate.expert.key,
+		query: delegate.query
+	};
+}
+function createInteractiveToolActivity(skillName, toolName, toolCall, reasoning) {
+	return {
+		type: "interactiveTool",
+		id: "",
+		expertKey: "",
+		runId: "",
+		reasoning,
+		skillName,
+		toolName,
+		args: toolCall.args
+	};
+}
+function createRetryActivity(newMessages, reasoning, customError) {
+	const textPart = newMessages[newMessages.length - 1]?.contents.find((c) => c.type === "textPart");
+	return {
+		type: "retry",
+		id: "",
+		expertKey: "",
+		runId: "",
+		reasoning,
+		error: customError ?? "No tool call or result found",
+		message: textPart?.text ?? ""
+	};
+}
+function createErrorActivity(checkpoint, reasoning) {
+	const error = checkpoint.error;
+	return {
+		type: "error",
+		id: "",
+		expertKey: "",
+		runId: "",
+		reasoning,
+		error: error?.message ?? "Unknown error",
+		errorName: error?.name,
+		isRetryable: error?.isRetryable
+	};
+}
+function createBaseToolActivity(toolName, toolCall, toolResult, reasoning) {
+	const args = toolCall.args;
+	const resultContents = toolResult.result;
+	const errorText = getErrorFromResult(resultContents);
+	const baseFields = {
+		id: "",
+		expertKey: "",
+		runId: "",
+		reasoning
+	};
+	switch (toolName) {
+		case "attemptCompletion": {
+			const remainingTodos = parseRemainingTodosFromResult(resultContents);
+			return {
+				type: "attemptCompletion",
+				...baseFields,
+				remainingTodos,
+				error: errorText
+			};
+		}
+		case "todo": {
+			const todos = parseTodosFromResult(resultContents);
+			return {
+				type: "todo",
+				...baseFields,
+				newTodos: Array.isArray(args["newTodos"]) ? args["newTodos"].map(String) : void 0,
+				completedTodos: Array.isArray(args["completedTodos"]) ? args["completedTodos"].map(Number) : void 0,
+				todos,
+				error: errorText
+			};
+		}
+		case "clearTodo": return {
+			type: "clearTodo",
+			...baseFields,
+			error: errorText
+		};
+		case "readImageFile": return {
+			type: "readImageFile",
+			...baseFields,
+			path: String(args["path"] ?? ""),
+			mimeType: parseStringField(resultContents, "mimeType"),
+			size: parseNumberField(resultContents, "size"),
+			error: errorText
+		};
+		case "readPdfFile": return {
+			type: "readPdfFile",
+			...baseFields,
+			path: String(args["path"] ?? ""),
+			mimeType: parseStringField(resultContents, "mimeType"),
+			size: parseNumberField(resultContents, "size"),
+			error: errorText
+		};
+		case "readTextFile": return {
+			type: "readTextFile",
+			...baseFields,
+			path: String(args["path"] ?? ""),
+			content: parseStringField(resultContents, "content"),
+			from: typeof args["from"] === "number" ? args["from"] : void 0,
+			to: typeof args["to"] === "number" ? args["to"] : void 0,
+			error: errorText
+		};
+		case "editTextFile": return {
+			type: "editTextFile",
+			...baseFields,
+			path: String(args["path"] ?? ""),
+			newText: String(args["newText"] ?? ""),
+			oldText: String(args["oldText"] ?? ""),
+			error: errorText
+		};
+		case "writeTextFile": return {
+			type: "writeTextFile",
+			...baseFields,
+			path: String(args["path"] ?? ""),
+			text: String(args["text"] ?? ""),
+			error: errorText
+		};
+		case "exec": return {
+			type: "exec",
+			...baseFields,
+			command: String(args["command"] ?? ""),
+			args: Array.isArray(args["args"]) ? args["args"].map(String) : [],
+			cwd: String(args["cwd"] ?? ""),
+			output: parseStringField(resultContents, "output"),
+			error: errorText,
+			stdout: parseStringField(resultContents, "stdout"),
+			stderr: parseStringField(resultContents, "stderr")
+		};
+		case "addSkill": return {
+			type: "addSkill",
+			...baseFields,
+			name: String(args["name"] ?? ""),
+			skillType: String(args["type"] ?? ""),
+			tools: parseStringArrayField(resultContents, "tools"),
+			error: errorText
+		};
+		case "removeSkill": return {
+			type: "removeSkill",
+			...baseFields,
+			skillName: String(args["skillName"] ?? ""),
+			error: errorText
+		};
+		case "addDelegate": return {
+			type: "addDelegate",
+			...baseFields,
+			targetExpertKey: String(args["expertKey"] ?? ""),
+			delegateToolName: parseStringField(resultContents, "delegateToolName"),
+			error: errorText
+		};
+		case "removeDelegate": return {
+			type: "removeDelegate",
+			...baseFields,
+			expertName: String(args["expertName"] ?? ""),
+			error: errorText
+		};
+		case "createExpert": return {
+			type: "createExpert",
+			...baseFields,
+			targetKey: String(args["key"] ?? ""),
+			description: typeof args["description"] === "string" ? args["description"] : void 0,
+			resultExpertKey: parseStringField(resultContents, "expertKey"),
+			error: errorText
+		};
+		default: return createGeneralToolActivity(toolCall.skillName, toolName, toolCall, toolResult, reasoning);
+	}
+}
+function createGeneralToolActivity(skillName, toolName, toolCall, toolResult, reasoning) {
+	const errorText = getErrorFromResult(toolResult.result);
+	return {
+		type: "generalTool",
+		id: "",
+		expertKey: "",
+		runId: "",
+		reasoning,
+		skillName,
+		toolName,
+		args: toolCall.args,
+		result: toolResult.result,
+		error: errorText
+	};
+}
+function getErrorFromResult(result) {
+	const textPart = result.find((p) => p.type === "textPart");
+	if (!textPart?.text) return void 0;
+	try {
+		const parsed = JSON.parse(textPart.text);
+		if (typeof parsed.error === "string") return parsed.error;
+	} catch {
+		const trimmed = textPart.text.trim();
+		if (trimmed.toLowerCase().startsWith("error:") || trimmed.toLowerCase().startsWith("error ")) return textPart.text;
+	}
+}
+function parseStringField(result, field) {
+	const textPart = result.find((p) => p.type === "textPart");
+	if (!textPart?.text) return void 0;
+	try {
+		const parsed = JSON.parse(textPart.text);
+		return typeof parsed[field] === "string" ? parsed[field] : void 0;
+	} catch {
+		return;
+	}
+}
+function parseNumberField(result, field) {
+	const textPart = result.find((p) => p.type === "textPart");
+	if (!textPart?.text) return void 0;
+	try {
+		const parsed = JSON.parse(textPart.text);
+		return typeof parsed[field] === "number" ? parsed[field] : void 0;
+	} catch {
+		return;
+	}
+}
+function parseStringArrayField(result, field) {
+	const textPart = result.find((p) => p.type === "textPart");
+	if (!textPart?.text) return void 0;
+	try {
+		const parsed = JSON.parse(textPart.text);
+		if (Array.isArray(parsed[field])) return parsed[field].map(String);
+	} catch {}
+}
+function parseRemainingTodosFromResult(result) {
+	const textPart = result.find((p) => p.type === "textPart");
+	if (!textPart?.text) return void 0;
+	try {
+		const parsed = JSON.parse(textPart.text);
+		if (Array.isArray(parsed.remainingTodos)) return parsed.remainingTodos.map((t, i) => ({
+			id: typeof t.id === "number" ? t.id : i,
+			title: typeof t.title === "string" ? t.title : "",
+			completed: typeof t.completed === "boolean" ? t.completed : false
+		}));
+	} catch {}
+}
+function parseTodosFromResult(result) {
+	const textPart = result.find((p) => p.type === "textPart");
+	if (!textPart?.text) return [];
+	try {
+		const parsed = JSON.parse(textPart.text);
+		if (Array.isArray(parsed.todos)) return parsed.todos.map((t, i) => ({
+			id: typeof t.id === "number" ? t.id : i,
+			title: typeof t.title === "string" ? t.title : "",
+			completed: typeof t.completed === "boolean" ? t.completed : false
+		}));
+	} catch {}
+	return [];
+}
+
+//#endregion
+//#region src/utils/env-filter.ts
+const SAFE_ENV_VARS = [
+	"PATH",
+	"HOME",
+	"SHELL",
+	"TERM",
+	"NODE_PATH",
+	"HTTP_PROXY",
+	"HTTPS_PROXY",
+	"http_proxy",
+	"https_proxy",
+	"NO_PROXY",
+	"no_proxy",
+	"PERSTACK_PROXY_URL",
+	"NPM_CONFIG_PROXY",
+	"NPM_CONFIG_HTTPS_PROXY"
+];
+const PROTECTED_ENV_VARS = new Set([
+	"PATH",
+	"HOME",
+	"SHELL",
+	"NODE_PATH",
+	"LD_PRELOAD",
+	"LD_LIBRARY_PATH",
+	"DYLD_INSERT_LIBRARIES",
+	"DYLD_LIBRARY_PATH",
+	"NODE_OPTIONS",
+	"PYTHONPATH",
+	"PERL5LIB",
+	"RUBYLIB"
+]);
+function getFilteredEnv(additional) {
+	const filtered = {};
+	for (const key of SAFE_ENV_VARS) if (process.env[key]) filtered[key] = process.env[key];
+	if (additional) {
+		for (const [key, value] of Object.entries(additional)) if (!PROTECTED_ENV_VARS.has(key.toUpperCase())) filtered[key] = value;
+	}
+	return filtered;
+}
+
+//#endregion
+//#region src/utils/event-filter.ts
+/**
+* Validate and parse event filter option
+* @param filter - Array of event type strings to validate
+* @returns The validated filter array
+* @throws Error if any event type is invalid
+*/
+function validateEventFilter(filter) {
+	const invalid = filter.filter((type) => !isValidEventType(type) && !isValidRuntimeEventType(type));
+	if (invalid.length > 0) throw new PerstackError(`Invalid event type(s): ${invalid.join(", ")}. Valid event types are: startRun, completeRun, stopRunByError, callTools, etc. See documentation for full list.`);
+	return filter;
+}
+/**
+* Create a filtered event listener that only emits events of allowed types
+* @param listener - The original event listener to wrap
+* @param allowedTypes - Set of event types to allow through
+* @returns A filtered event listener
+*/
+function createFilteredEventListener(listener, allowedTypes) {
+	return (event) => {
+		if (allowedTypes.has(event.type)) listener(event);
+	};
+}
+
+//#endregion
+//#region src/utils/zod-error.ts
+function formatZodError(error) {
+	return `Validation failed:\n${error.issues.map((issue) => {
+		return `  - ${issue.path.length > 0 ? `${issue.path.join(".")}: ` : ""}${issue.message}`;
+	}).join("\n")}`;
+}
+function parseWithFriendlyError(schema, data, context) {
+	const result = schema.safeParse(data);
+	if (result.success) return result.data;
+	throw new PerstackError(`${context ? `${context}: ` : ""}${formatZodError(result.error)}`);
+}
+
+//#endregion
+export { BASE_SKILL_PREFIX, PerstackError, SAFE_ENV_VARS, activityOrGroupSchema, activitySchema, addDelegateActivitySchema, addSkillActivitySchema, amazonBedrockProviderConfigSchema, anthropicProviderConfigSchema, anthropicProviderSkillSchema, anthropicProviderToolNameSchema, attemptCompletionActivitySchema, azureOpenAIProviderToolNameSchema, azureOpenAiProviderConfigSchema, basePartSchema, builtinAnthropicSkillSchema, callTools, checkpointSchema, checkpointStatusSchema, clearTodoActivitySchema, completeActivitySchema, completeRun, continueToNextStep, createBaseToolActivity, createCallToolsEvent, createCompleteRunEvent, createEmptyUsage, createEvent, createExpertActivitySchema, createFilteredEventListener, createGeneralToolActivity, createNormalizedCheckpoint, createResolveToolResultsEvent, createRuntimeEvent, createRuntimeInitEvent, createStartRunEvent, createStreamingEvent, createToolMessage, customAnthropicSkillSchema, deepseekProviderConfigSchema, defaultMaxRetries, defaultPerstackApiBaseUrl, defaultReasoningBudget, defaultTimeout, delegateActivitySchema, delegationCompleteActivitySchema, delegationTargetSchema, domainPatternSchema, editTextFileActivitySchema, errorActivitySchema, execActivitySchema, expertBaseSchema, expertKeyRegex, expertMessageSchema, expertNameRegex, expertSchema, expertVersionRegex, fileBinaryPartSchema, fileInlinePartSchema, fileSearchOptionsSchema, fileUrlPartSchema, finishMcpTools, finishToolCall, formatZodError, generalToolActivitySchema, getActivities, getExpertScope, getExpertShortName, getExpertType, getFilteredEnv, googleGenerativeAiProviderConfigSchema, googleProviderToolNameSchema, googleVertexProviderConfigSchema, headersSchema, imageBinaryPartSchema, imageInlinePartSchema, imageUrlPartSchema, instructionMessageSchema, interactiveSkillSchema, interactiveToolActivitySchema, interactiveToolSchema, isCoordinatorExpert, isDelegateExpert, isPrivateOrLocalIP, isValidEventType, isValidRuntimeEventType, jobSchema, jobStatusSchema, knownModels, lockfileExpertSchema, lockfileSchema, lockfileToolDefinitionSchema, maxExpertNameLength, maxSkillNameLength, maxSkillToolNameLength, mcpSseSkillSchema, mcpStdioSkillSchema, messagePartSchema, messageSchema, ollamaProviderConfigSchema, openAiProviderConfigSchema, openaiProviderToolNameSchema, parallelActivitiesGroupSchema, parseExpertKey, parseWithFriendlyError, perstackConfigSchema, proceedToInteractiveTools, providerConfigSchema, providerNameSchema, providerTableSchema, providerToolOptionsSchema, queryActivitySchema, readImageFileActivitySchema, readPdfFileActivitySchema, readTextFileActivitySchema, reasoningBudgetSchema, removeDelegateActivitySchema, removeSkillActivitySchema, resolveToolResults, resumeFromStop, resumeToolCalls, retry, retryActivitySchema, runCommandInputSchema, runParamsSchema, runSettingSchema, runtimeVersionSchema, skillSchema, skipDelegates, startCommandInputSchema, startGeneration, startRun, stepSchema, stopRunByDelegate, stopRunByError, stopRunByInteractiveTool, tagNameRegex, textPartSchema, thinkingPartSchema, todoActivitySchema, toolCallPartSchema, toolCallSchema, toolMessageSchema, toolResultPartSchema, toolResultSchema, usageSchema, userMessageSchema, validateAllDelegations, validateDelegation, validateEventFilter, vertexProviderToolNameSchema, webFetchOptionsSchema, webSearchOptionsSchema, writeTextFileActivitySchema };
 //# sourceMappingURL=index.js.map