@zihanw/pi-forge 0.1.0 → 0.2.0

package/src/loader.ts

@@ -6,6 +6,10 @@ import type {
 	PromptStackDiagnostic,
 	PromptStackItem,
 	PromptStackRole,
+	PromptStateConfig,
+	PromptStateDefinition,
+	PromptStateScope,
+	PromptStateValue,
 } from "./types.ts";
 import { SUPPORTED_SLOTS } from "./types.ts";
 
@@ -26,7 +30,30 @@ export function loadPromptStacks(cwd: string): LoadedPromptStack[] {
 		return [];
 	}
 
-	return entries.sort().map((name) => loadPromptStackFile(join(dir, name)));
+	const loaded = entries.sort().map((name) => loadPromptStackFile(join(dir, name)));
+	annotateDuplicateStackIds(loaded);
+	return loaded;
+}
+
+function annotateDuplicateStackIds(stacks: LoadedPromptStack[]): void {
+	const byId = new Map<string, LoadedPromptStack[]>();
+	for (const loaded of stacks) {
+		const id = loaded.stack.id;
+		const matches = byId.get(id) ?? [];
+		matches.push(loaded);
+		byId.set(id, matches);
+	}
+
+	for (const [id, matches] of byId) {
+		if (matches.length <= 1) continue;
+		const files = matches.map((loaded) => basename(loaded.filePath)).join(", ");
+		for (const loaded of matches) {
+			loaded.diagnostics.push({
+				level: "error",
+				message: `Duplicate stack id: ${id} appears in multiple files (${files}).`,
+			});
+		}
+	}
 }
 
 export function chooseDefaultStack(
@@ -123,6 +150,7 @@ function normalizeStack(raw: unknown, filePath: string, diagnostics: PromptStack
 		defaults: isPlainObject(obj.defaults) ? (obj.defaults as PromptStack["defaults"]) : undefined,
 		context: isPlainObject(obj.context) ? (obj.context as PromptStack["context"]) : undefined,
 		variables: normalizeStringRecord(obj.variables),
+		state: normalizeStateConfig(obj.state, diagnostics),
 		items,
 		import: isPlainObject(obj.import) ? (obj.import as Record<string, unknown>) : undefined,
 	};
@@ -225,3 +253,57 @@ function normalizeStringRecord(value: unknown): Record<string, string> | undefin
 	}
 	return result;
 }
+
+function normalizeStateConfig(value: unknown, diagnostics: PromptStackDiagnostic[]): PromptStateConfig | undefined {
+	if (value === undefined) return undefined;
+	if (!isPlainObject(value)) {
+		diagnostics.push({ level: "warning", message: "state must be an object when provided." });
+		return undefined;
+	}
+
+	const definitionsRaw = value.definitions;
+	const definitions: Record<string, PromptStateDefinition> = {};
+
+	if (definitionsRaw !== undefined && !isPlainObject(definitionsRaw)) {
+		diagnostics.push({ level: "warning", message: "state.definitions must be an object when provided." });
+	}
+
+	if (isPlainObject(definitionsRaw)) {
+		for (const [name, rawDefinition] of Object.entries(definitionsRaw)) {
+			if (!isPlainObject(rawDefinition)) {
+				diagnostics.push({ level: "warning", message: `state definition for ${name} must be an object.` });
+				continue;
+			}
+
+			const definition: PromptStateDefinition = {};
+			if (typeof rawDefinition.type === "string") definition.type = rawDefinition.type;
+			if (isStateScope(rawDefinition.scope)) definition.scope = rawDefinition.scope;
+			if (typeof rawDefinition.description === "string") definition.description = rawDefinition.description;
+			if (typeof rawDefinition.agentWritable === "boolean") definition.agentWritable = rawDefinition.agentWritable;
+			if (typeof rawDefinition.userWritable === "boolean") definition.userWritable = rawDefinition.userWritable;
+			if (isPromptStateValue(rawDefinition.default)) definition.default = rawDefinition.default;
+			else if (rawDefinition.default !== undefined) {
+				diagnostics.push({ level: "warning", message: `state definition default for ${name} is not a JSON-compatible value.` });
+			}
+			definitions[name] = definition;
+		}
+	}
+
+	return {
+		schemaVersion: value.schemaVersion === 1 ? 1 : undefined,
+		definitions: Object.keys(definitions).length > 0 ? definitions : undefined,
+	};
+}
+
+function isStateScope(value: unknown): value is PromptStateScope {
+	return value === "static" || value === "session" || value === "turn";
+}
+
+function isPromptStateValue(value: unknown): value is PromptStateValue {
+	if (value === null) return true;
+	const type = typeof value;
+	if (type === "string" || type === "number" || type === "boolean") return Number.isFinite(value as number) || type !== "number";
+	if (Array.isArray(value)) return value.every(isPromptStateValue);
+	if (!isPlainObject(value)) return false;
+	return Object.values(value).every(isPromptStateValue);
+}

package/src/sillytavern-importer.ts

@@ -55,14 +55,33 @@ const MARKER_SKIP = new Set([
 // ── ST macros that pi-forge handles natively ───────────────────────────────
 
 const NATIVE_MACROS = new Set([
-	"char",           // → static variable
-	"user",           // → static variable
-	"lastUserMessage", // → handled by pi-forge runtime
+	"char",            // → static variable
+	"user",            // → static variable
+	"lastusermessage", // → handled by pi-forge runtime
 	"cwd",
 	"date",
 	"time",
 ]);
 
+const MACRO_DISPLAY_NAMES: Record<string, string> = {
+	lastusermessage: "lastUserMessage",
+	groupnotmuted: "groupNotMuted",
+	notchar: "notChar",
+	charifnotgroup: "charIfNotGroup",
+	mesexamples: "mesExamples",
+	mesexamplesraw: "mesExamplesRaw",
+	charprompt: "charPrompt",
+	charinstruction: "charInstruction",
+	charversion: "charVersion",
+	charfirstmessage: "charFirstMessage",
+	wibefore: "wiBefore",
+	wiafter: "wiAfter",
+	lorebefore: "loreBefore",
+	loreafter: "loreAfter",
+	anchorbefore: "anchorBefore",
+	anchorafter: "anchorAfter",
+};
+
 // ── ST macros that need manual migration ───────────────────────────────────
 
 const MACRO_NEEDS_MIGRATION: Record<string, string> = {
@@ -78,26 +97,26 @@ const MACRO_NEEDS_MIGRATION: Record<string, string> = {
 	"original": "SillyTavern-specific — no direct equivalent; set as session variable if needed",
 	"outlet": "SillyTavern extension outlet — no pi-forge equivalent",
 	"group": "SillyTavern group chat — no pi-forge equivalent",
-	"groupNotMuted": "SillyTavern group chat — no pi-forge equivalent",
-	"notChar": "SillyTavern group chat — no pi-forge equivalent",
-	"charIfNotGroup": "SillyTavern group chat — no pi-forge equivalent",
+	"groupnotmuted": "SillyTavern group chat — no pi-forge equivalent",
+	"notchar": "SillyTavern group chat — no pi-forge equivalent",
+	"charifnotgroup": "SillyTavern group chat — no pi-forge equivalent",
 	"description": "ST character card field — set as session variable or static variable if needed",
 	"personality": "ST character card field — set as session variable or static variable if needed",
 	"scenario": "ST character card field — set as session variable or static variable if needed",
 	"persona": "ST persona field — set as session variable or static variable if needed",
-	"mesExamples": "ST character dialogue examples — add inline or as context file if needed",
-	"mesExamplesRaw": "ST character dialogue examples — add inline or as context file if needed",
-	"charPrompt": "ST character prompt override — merge into system prompt blocks if needed",
-	"charInstruction": "ST character instruction override — merge into post-history blocks if needed",
-	"charVersion": "ST character version — set as static variable if needed",
-	"charFirstMessage": "ST character first message — add as static variable if needed",
+	"mesexamples": "ST character dialogue examples — add inline or as context file if needed",
+	"mesexamplesraw": "ST character dialogue examples — add inline or as context file if needed",
+	"charprompt": "ST character prompt override — merge into system prompt blocks if needed",
+	"charinstruction": "ST character instruction override — merge into post-history blocks if needed",
+	"charversion": "ST character version — set as static variable if needed",
+	"charfirstmessage": "ST character first message — add as static variable if needed",
 	"system": "ST context template system prompt — handled by pi-forge system prompt replacement",
-	"wiBefore": "ST world info — no pi-forge equivalent; merge relevant lore into static blocks",
-	"wiAfter": "ST world info — no pi-forge equivalent; merge relevant lore into static blocks",
-	"loreBefore": "ST world info — no pi-forge equivalent; merge relevant lore into static blocks",
-	"loreAfter": "ST world info — no pi-forge equivalent; merge relevant lore into static blocks",
-	"anchorBefore": "ST extension injection point — no pi-forge equivalent",
-	"anchorAfter": "ST extension injection point — no pi-forge equivalent",
+	"wibefore": "ST world info — no pi-forge equivalent; merge relevant lore into static blocks",
+	"wiafter": "ST world info — no pi-forge equivalent; merge relevant lore into static blocks",
+	"lorebefore": "ST world info — no pi-forge equivalent; merge relevant lore into static blocks",
+	"loreafter": "ST world info — no pi-forge equivalent; merge relevant lore into static blocks",
+	"anchorbefore": "ST extension injection point — no pi-forge equivalent",
+	"anchorafter": "ST extension injection point — no pi-forge equivalent",
 };
 
 // ── Macros we can strip entirely (produce no output) ───────────────────────
@@ -118,6 +137,12 @@ export interface SillyTavernImportError {
 
 export type SillyTavernImportOutcome = SillyTavernImportResult | SillyTavernImportError;
 
+export interface SillyTavernConvertOptions {
+	sourceName?: string;
+	sourcePath?: string;
+	characterId?: number;
+}
+
 // ── Importer ───────────────────────────────────────────────────────────────
 
 export function importSillyTavernPreset(
@@ -135,7 +160,25 @@ export function importSillyTavernPreset(
 		return { error: "Preset root must be a JSON object." };
 	}
 
+	return convertSillyTavernPreset(raw, { sourceName: filePath, sourcePath: filePath, characterId });
+}
+
+export function convertSillyTavernPreset(
+	raw: unknown,
+	options: SillyTavernConvertOptions = {},
+): SillyTavernImportOutcome {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+		return { error: "Preset root must be a JSON object." };
+	}
+
 	const preset = raw as StPreset;
+	const fallbackName = typeof preset.preset_name === "string" && preset.preset_name.trim()
+		? preset.preset_name
+		: typeof preset.name === "string" && preset.name.trim()
+			? preset.name
+			: "imported.json";
+	const sourceName = options.sourceName ?? fallbackName;
+	const sourcePath = options.sourcePath ?? sourceName;
 	const allPrompts = preset.prompts ?? [];
 	const promptOrder = preset.prompt_order ?? [];
 
@@ -144,14 +187,14 @@ export function importSillyTavernPreset(
 	}
 
 	// Select character_id
-	const selectedEntry = selectCharacterEntry(promptOrder, characterId);
+	const selectedEntry = selectCharacterEntry(promptOrder, options.characterId);
 	if (!selectedEntry) {
 		const ids = promptOrder.map((entry) => entry.character_id);
 		if (ids.length === 0) {
-			return { error: "Preset has no prompt_order entries. Specify a character_id with /preset import-silly <path> <character_id>." };
+			return { error: "Preset has no prompt_order entries. Choose a character_id and retry." };
 		}
 		return {
-			error: `Multiple character configs found: [${ids.join(", ")}]. Re-run with /preset import-silly <path> <character_id>.`,
+			error: `Multiple character configs found: [${ids.join(", ")}]. Choose a character_id and retry.`,
 		};
 	}
 
@@ -219,8 +262,8 @@ export function importSillyTavernPreset(
 			continue;
 		}
 
-		// Detect {{lastUserMessage}} usage
-		if (content.includes("{{lastUserMessage}}")) {
+		// Detect {{lastUserMessage}} usage, case-insensitively.
+		if (/\{\{\s*lastUserMessage\b/i.test(content)) {
 			usesLastUserMessage = true;
 		}
 
@@ -258,7 +301,7 @@ export function importSillyTavernPreset(
 	}
 
 	// Build stack name from file
-	const fileName = basename(filePath, ".json");
+	const fileName = basename(sourceName).replace(/\.json$/i, "") || "imported";
 	const styleName = preset.names_behavior === 1 ? "names" : preset.names_behavior === 2 ? "nonames" : "default";
 	const stackId = fileName.replace(/[^a-zA-Z0-9_-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").toLowerCase() || "imported";
 
@@ -285,7 +328,8 @@ export function importSillyTavernPreset(
 		},
 	};
 
-	// Add chat-history option if {{lastUserMessage}} is used after history
+	// Add chat-history option if {{lastUserMessage}} is used after history.
+	if (macroUsage.detected.has("lastusermessage")) usesLastUserMessage = true;
 	if (usesLastUserMessage) {
 		const chatHistoryItem = items.find(
 			(item) => item.kind === "slot" && item.slot === "chat-history",
@@ -299,7 +343,7 @@ export function importSillyTavernPreset(
 	const reportLines: string[] = [];
 	reportLines.push(`# SillyTavern Import Report: ${fileName}`);
 	reportLines.push("");
-	reportLines.push(`- **Source file**: ${filePath}`);
+	reportLines.push(`- **Source file**: ${sourcePath}`);
 	reportLines.push(`- **Character ID**: ${selectedEntry.character_id}`);
 	reportLines.push(`- **Output stack ID**: ${stackId}`);
 	reportLines.push(`- **Names behavior**: ${styleName} (ST value ${preset.names_behavior ?? "?"})`);
@@ -353,7 +397,7 @@ export function importSillyTavernPreset(
 			reportLines.push(`- \`${key}\` = \`${val}\` — replace with your character/persona name`);
 		}
 		reportLines.push("");
-		reportLines.push("Use `/preset vars set <name> <value>` or edit the stack JSON to set real values.");
+		reportLines.push("Use `/state set <name> <value>` or edit the stack JSON to set real values.");
 		reportLines.push("");
 	}
 
@@ -366,7 +410,7 @@ export function importSillyTavernPreset(
 		reportLines.push("");
 		for (const [name, count] of migrationEntries) {
 			const note = MACRO_NEEDS_MIGRATION[name] ?? "no mapping available";
-			reportLines.push(`- **\`{{${name}}}\`** (${count} occurrence${count > 1 ? "s" : ""}) — ${note}`);
+			reportLines.push(`- **\`{{${displayMacroName(name)}}}\`** (${count} occurrence${count > 1 ? "s" : ""}) — ${note}`);
 		}
 		reportLines.push("");
 
@@ -377,7 +421,7 @@ export function importSillyTavernPreset(
 			reportLines.push("ST uses `setvar`/`getvar` for ephemeral state. pi-forge has a different variable model:");
 			reportLines.push("");
 			reportLines.push("- **Static variables** — set in the stack JSON's `variables` object (character names, fixed config)");
-			reportLines.push("- **Session variables** — persist across turns, set via `/preset vars set` or `forge_set_var` tool");
+			reportLines.push("- **Session state** — persists across turns, set by the user via `/state set` or by the agent via `forge_state_set` for `agent.*` names");
 			reportLines.push("- **Turn variables** — ephemeral, set via `{{setvar::name::value}}` macros in blocks");
 			reportLines.push("");
 			reportLines.push("Review ST `setvar`/`getvar` calls and migrate to the appropriate pi-forge scope.");
@@ -391,12 +435,13 @@ export function importSillyTavernPreset(
 		reportLines.push("## Handled macros");
 		reportLines.push("");
 		for (const name of nativeDetected) {
+			const displayName = displayMacroName(name);
 			if (name === "char" || name === "user") {
-				reportLines.push(`- \`{{${name}}}\` → auto-populated as static variable`);
-			} else if (name === "lastUserMessage") {
-				reportLines.push(`- \`{{${name}}}\` → handled by pi-forge runtime (chat-history slot)`);
+				reportLines.push(`- \`{{${displayName}}}\` → auto-populated as static variable`);
+			} else if (name === "lastusermessage") {
+				reportLines.push(`- \`{{${displayName}}}\` → handled by pi-forge runtime (chat-history slot)`);
 			} else {
-				reportLines.push(`- \`{{${name}}}\` → handled natively by pi-forge`);
+				reportLines.push(`- \`{{${displayName}}}\` → handled natively by pi-forge`);
 			}
 		}
 		reportLines.push("");
@@ -434,7 +479,7 @@ export function importSillyTavernPreset(
 	reportLines.push("");
 	reportLines.push("## Suggested next steps");
 	reportLines.push("");
-	reportLines.push("1. Set real values for auto-populated variables with `/preset vars set`.");
+	reportLines.push("1. Set real values for auto-populated variables with `/state set`.");
 	reportLines.push("2. Review items with migration-needed macros and rewrite for pi-forge's macro system.");
 	reportLines.push("3. Consider adding a `variables` slot for agent state visibility.");
 	reportLines.push(`4. Run \`/preset validate ${stackId}\` to check for issues.`);
@@ -495,6 +540,10 @@ function detectMacros(conversionItems: StConversionItem[]): MacroDetection {
 
 // ── Content cleaning ──────────────────────────────────────────────────────
 
+function displayMacroName(name: string): string {
+	return MACRO_DISPLAY_NAMES[name] ?? name;
+}
+
 function cleanContent(content: string): string {
 	// Collapse multiple blank lines (max 1 blank line between paragraphs)
 	return content.replace(/\n{3,}/g, "\n\n").trim();

package/src/types.ts

@@ -50,6 +50,18 @@ export interface VariablesSlotOptions {
 	includeSession?: boolean;
 	/** Include turn variables. Default: true. */
 	includeTurn?: boolean;
+	/** Include only these scopes. Overrides includeStatic/includeSession/includeTurn when present. */
+	includeScopes?: PromptStateScope[];
+	/** Include variable names matching these exact names or wildcard prefixes, e.g. agent.*. */
+	includeNamespaces?: string[];
+	/** Exclude variable names matching these exact names or wildcard prefixes. */
+	excludeNamespaces?: string[];
+	/** Include type and description metadata from stack.state.definitions. Default: false. */
+	includeMetadata?: boolean;
+	/** Render format. Default: xml. */
+	format?: "xml" | "json";
+	/** Truncate each rendered value after this many characters. */
+	maxValueChars?: number;
 }
 
 export interface PromptStackSlotOptions {
@@ -59,6 +71,12 @@ export interface PromptStackSlotOptions {
 	includeStatic?: boolean;
 	includeSession?: boolean;
 	includeTurn?: boolean;
+	includeScopes?: PromptStateScope[];
+	includeNamespaces?: string[];
+	excludeNamespaces?: string[];
+	includeMetadata?: boolean;
+	format?: "xml" | "json";
+	maxValueChars?: number;
 	[key: string]: unknown;
 }
 
@@ -70,6 +88,26 @@ export interface PromptStackSlotItem extends PromptStackBaseItem {
 
 export type PromptStackItem = PromptStackBlockItem | PromptStackSlotItem;
 
+export type PromptStatePrimitive = string | number | boolean | null;
+
+export type PromptStateValue = PromptStatePrimitive | PromptStateValue[] | { [key: string]: PromptStateValue };
+
+export type PromptStateScope = "static" | "session" | "turn";
+
+export interface PromptStateDefinition {
+	type?: string;
+	scope?: PromptStateScope;
+	description?: string;
+	agentWritable?: boolean;
+	userWritable?: boolean;
+	default?: PromptStateValue;
+}
+
+export interface PromptStateConfig {
+	schemaVersion?: 1;
+	definitions?: Record<string, PromptStateDefinition>;
+}
+
 export interface PromptStack {
 	schemaVersion: 1;
 	type?: "pi-forge.prompt-stack";
@@ -81,6 +119,7 @@ export interface PromptStack {
 	defaults?: PromptStackDefaults;
 	context?: PromptStackContextOptions;
 	variables?: Record<string, string>;
+	state?: PromptStateConfig;
 	items: PromptStackItem[];
 	import?: Record<string, unknown>;
 }
@@ -100,8 +139,8 @@ export interface PromptStackDiagnostic {
 }
 
 export interface PromptVariableStore {
-	turn: Record<string, string>;
-	session: Record<string, string>;
+	turn: Record<string, PromptStateValue>;
+	session: Record<string, PromptStateValue>;
 	sessionDirty?: boolean;
 }