@aeondave/pi-skill-optimizer 3.0.0

package/src/init-profile.ts

@@ -0,0 +1,96 @@
+import type { ProfileWrite, StoredProfile } from "./persistence.ts";
+import {
+	EMPTY_PROFILE,
+	splitProfileByScope,
+	type SkillOptimizerProfile,
+} from "./profile.ts";
+
+function pickKeys(record: Record<string, string>, keep: (name: string) => boolean): Record<string, string> {
+	return Object.fromEntries(Object.entries(record).filter(([name]) => keep(name)));
+}
+
+function ownedProfileNames(profile: SkillOptimizerProfile): Set<string> {
+	return new Set([
+		...profile.critical,
+		...Object.keys(profile.queries),
+		...Object.keys(profile.negativeHints),
+		...Object.keys(profile.activation ?? {}),
+		...Object.values(profile.clusters).flat(),
+	]);
+}
+
+function storedNames(stored: StoredProfile | undefined): Set<string> {
+	if (!stored?.exists) return new Set();
+	return new Set([
+		...Object.keys(stored.hashes),
+		...ownedProfileNames(stored.profile),
+	]);
+}
+
+/** Detect profile/hash ownership that no longer matches Pi's current skill scope. */
+export function needsProfileScopeRepair(options: {
+	paths: { global: string; project: string };
+	projectNames: ReadonlySet<string>;
+	global: StoredProfile;
+	project?: StoredProfile;
+}): boolean {
+	if (options.paths.global === options.paths.project) return false;
+	if (options.projectNames.size > 0 && !options.project?.exists) return true;
+	for (const name of storedNames(options.global)) {
+		if (options.projectNames.has(name)) return true;
+	}
+	for (const name of storedNames(options.project)) {
+		if (!options.projectNames.has(name)) return true;
+	}
+	return false;
+}
+
+/** Build the complete global/project checkpoint from one merged profile snapshot. */
+export function buildInitProfileWrites(options: {
+	paths: { global: string; project: string };
+	profile: SkillOptimizerProfile;
+	hashes: Record<string, string>;
+	skillCount: number;
+	projectNames: ReadonlySet<string>;
+	globalRevision: string | null;
+	projectRevision: string | null;
+	projectExists: boolean;
+}): ProfileWrite[] {
+	const split = options.paths.project !== options.paths.global && options.projectNames.size > 0;
+	if (!split) {
+		const writes: ProfileWrite[] = [{
+			path: options.paths.global,
+			profile: options.profile,
+			skillCount: options.skillCount,
+			hashes: options.hashes,
+			expectedRevision: options.globalRevision,
+		}];
+		if (options.projectExists) {
+			writes.push({
+				path: options.paths.project,
+				profile: EMPTY_PROFILE,
+				skillCount: 0,
+				hashes: {},
+				expectedRevision: options.projectRevision,
+			});
+		}
+		return writes;
+	}
+	const scoped = splitProfileByScope(options.profile, options.projectNames);
+	return [
+		{
+			path: options.paths.global,
+			profile: scoped.global,
+			skillCount: Object.keys(options.hashes).filter((name) => !options.projectNames.has(name)).length,
+			hashes: pickKeys(options.hashes, (name) => !options.projectNames.has(name)),
+			expectedRevision: options.globalRevision,
+		},
+		{
+			path: options.paths.project,
+			profile: scoped.project,
+			skillCount: Object.keys(options.hashes).filter((name) => options.projectNames.has(name)).length,
+			hashes: pickKeys(options.hashes, (name) => options.projectNames.has(name)),
+			expectedRevision: options.projectRevision,
+		},
+	];
+}

package/src/init-prompt.ts

@@ -0,0 +1,10 @@
+import { readFileSync } from "node:fs";
+import { ACTIVATION_TASKS } from "./activation.ts";
+
+/** Bump only when an explicit init must regenerate previously current hints. */
+export const INIT_PROFILE_VERSION = 5;
+
+export const INIT_PROFILE_PROMPT = readFileSync(
+	new URL("./prompts/init-profile.md", import.meta.url),
+	"utf8",
+).replace("{{ACTIVATION_TASKS}}", JSON.stringify(ACTIVATION_TASKS));

package/src/init-readiness.ts

@@ -0,0 +1,123 @@
+import { createHash } from "node:crypto";
+
+import { diffSkills, type SkillOptimizerProfile, type SkillRef } from "./profile.ts";
+
+export const INIT_READINESS_ENTRY_TYPE = "skill-optimizer-init-readiness";
+
+export type InitReadinessStatus = "empty" | "manual" | "outdated" | "incomplete" | "current";
+export type InitNoticeStatus = Extract<InitReadinessStatus, "empty" | "outdated" | "incomplete">;
+
+export interface InitReadinessProfile {
+	exists: boolean;
+	profile: SkillOptimizerProfile;
+	hashes: Record<string, string>;
+	initVersion: number;
+}
+
+export interface InitReadinessScope {
+	stored: InitReadinessProfile;
+	skills: readonly SkillRef[];
+}
+
+export interface InitReadinessInput {
+	scopeKey: string;
+	initVersion: number;
+	global: InitReadinessScope;
+	project?: InitReadinessScope;
+}
+
+export interface InitReadiness {
+	status: InitReadinessStatus;
+	skillCount: number;
+	catalogKey: string;
+}
+
+function hasProfileContent(profile: SkillOptimizerProfile): boolean {
+	return profile.critical.length > 0
+		|| Object.keys(profile.queries).length > 0
+		|| Object.keys(profile.clusters).length > 0
+		|| Object.keys(profile.negativeHints).length > 0
+		|| Object.keys(profile.activation ?? {}).length > 0;
+}
+
+function hasGeneratedMetadata(stored: InitReadinessProfile): boolean {
+	return stored.initVersion > 0 || Object.keys(stored.hashes).length > 0;
+}
+
+function digest(value: string): string {
+	return createHash("sha256").update(value, "utf8").digest("hex");
+}
+
+export function buildInitCatalogKey(input: InitReadinessInput): string {
+	const scopes = [
+		{ name: "global", skills: input.global.skills },
+		...(input.project ? [{ name: "project", skills: input.project.skills }] : []),
+	];
+	return JSON.stringify(scopes.map((scope) => [
+		scope.name,
+		scope.skills.map((skill) => [skill.name, skill.description]),
+	]));
+}
+
+/** Evaluate generated metadata separately from optional profile fields such as activation tags. */
+export function buildInitReadiness(input: InitReadinessInput, catalogKey = buildInitCatalogKey(input)): InitReadiness {
+	const scopes = [
+		{ name: "global", ...input.global },
+		...(input.project ? [{ name: "project", ...input.project }] : []),
+	];
+	const skillCount = scopes.reduce((count, scope) => count + scope.skills.length, 0);
+	const populated = scopes.filter((scope) => scope.stored.exists && hasProfileContent(scope.stored.profile));
+	const generated = scopes.filter((scope) => scope.stored.exists && hasGeneratedMetadata(scope.stored));
+
+	if (generated.length === 0 && populated.length === 0) {
+		return { status: "empty", skillCount, catalogKey };
+	}
+	if (generated.some((scope) => scope.stored.initVersion !== input.initVersion)) {
+		return { status: "outdated", skillCount, catalogKey };
+	}
+
+	for (const scope of scopes) {
+		const manual = scope.stored.exists
+			&& hasProfileContent(scope.stored.profile)
+			&& !hasGeneratedMetadata(scope.stored);
+		if (manual) continue;
+		if (!scope.stored.exists) {
+			if (scope.skills.length > 0) return { status: "incomplete", skillCount, catalogKey };
+			continue;
+		}
+		if (!hasGeneratedMetadata(scope.stored)) {
+			if (scope.skills.length > 0) return { status: "incomplete", skillCount, catalogKey };
+			continue;
+		}
+		const diff = diffSkills(scope.skills, scope.stored.hashes);
+		if (diff.changed.length > 0 || diff.removed.length > 0) {
+			return { status: "incomplete", skillCount, catalogKey };
+		}
+	}
+
+	if (populated.some((scope) => !hasGeneratedMetadata(scope.stored))) {
+		return { status: "manual", skillCount, catalogKey };
+	}
+	return { status: "current", skillCount, catalogKey };
+}
+
+/** A bounded, non-sensitive marker key for one scope, init version, and actionable readiness state. */
+export function buildInitNoticeKey(scopeKey: string, initVersion: number, status: InitNoticeStatus): string {
+	return digest(JSON.stringify([scopeKey, initVersion, status]));
+}
+
+/** Recover notice keys from Pi's custom session entries, which are not LLM messages. */
+export function readInitNoticeKeys(entries: readonly unknown[]): Set<string> {
+	const keys = new Set<string>();
+	for (const entry of entries) {
+		if (!entry || typeof entry !== "object") continue;
+		const candidate = entry as { type?: unknown; customType?: unknown; data?: unknown };
+		if (candidate.type !== "custom" || candidate.customType !== INIT_READINESS_ENTRY_TYPE) continue;
+		if (!candidate.data || typeof candidate.data !== "object") continue;
+		const data = candidate.data as { schema?: unknown; key?: unknown };
+		if (data.schema === 1 && typeof data.key === "string" && /^[a-f0-9]{64}$/.test(data.key)) {
+			keys.add(data.key);
+		}
+	}
+	return keys;
+}

package/src/optimize.ts

@@ -0,0 +1,424 @@
+import {
+  planSkillPrefetch,
+  inspectStableSkillCatalog,
+  renderStableSkillCatalog,
+  renderSkillPrefetch,
+  type Skill,
+} from "./skills.js";
+import {
+  appendToLatestHumanInput,
+  extractRequestQuery,
+  normalizeRequest,
+} from "./request.js";
+
+export interface OptimizeProfile {
+  critical: string[];
+  queries: Record<string, string[]>;
+  clusters: Record<string, string[]>;
+  negativeHints: Record<string, string[]>;
+}
+
+export interface OptimizeConfig {
+  catalogBudgetChars: number;
+  intentMaxChars: number;
+  prefetchTarget: number;
+  prefetchMin: number;
+  prefetchMax: number;
+  prefetchBudgetChars: number;
+  fuzzyCandidateLimit: number;
+  profile?: OptimizeProfile;
+  usagePrior?: Readonly<Record<string, number>> | ReadonlyMap<string, number>;
+  alwaysSkills?: string[];
+  excludeSkills?: string[];
+}
+
+export interface OptimizeBudget extends SkillCatalogBudget {
+  catalogs: number;
+}
+
+export interface OptimizeResult<T> {
+  next: T;
+  removedChars: number;
+  baseRemovedChars: number;
+  addedPrefetchChars: number;
+  selected: string[];
+  catalogNames: string[];
+  fingerprints: string[];
+  budget: OptimizeBudget;
+}
+
+type SkillCatalogBudget = ReturnType<typeof renderStableSkillCatalog>["budget"];
+
+const PREFETCH_MARKER = "<!--skill-optimizer:prefetch:v2-->";
+
+interface TextBlock {
+  type?: unknown;
+  text?: unknown;
+  [key: string]: unknown;
+}
+
+interface MessageLike {
+  role?: unknown;
+  content?: unknown;
+  [key: string]: unknown;
+}
+
+interface ToolLike {
+  description?: unknown;
+  function?: unknown;
+  [key: string]: unknown;
+}
+
+interface PayloadLike {
+  system?: unknown;
+  systemInstruction?: unknown;
+  instructions?: unknown;
+  messages?: unknown;
+  input?: unknown;
+  context?: unknown;
+  tools?: unknown;
+  [key: string]: unknown;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function serializedLength(value: unknown): number {
+  try {
+    return JSON.stringify(value).length;
+  } catch {
+    return Number.POSITIVE_INFINITY;
+  }
+}
+
+function emptyBudget(config: OptimizeConfig): OptimizeBudget {
+  return {
+    requestedChars: config.catalogBudgetChars,
+    usedChars: 0,
+    floorChars: 0,
+    intentCount: 0,
+    nameOnlyCount: 0,
+    overBudgetChars: 0,
+    catalogs: 0,
+  };
+}
+
+function mergeBudget(
+  target: OptimizeBudget,
+  source: SkillCatalogBudget,
+): void {
+  target.usedChars += source.usedChars;
+  target.floorChars += source.floorChars;
+  target.intentCount += source.intentCount;
+  target.nameOnlyCount += source.nameOnlyCount;
+  target.overBudgetChars += source.overBudgetChars;
+  target.catalogs += 1;
+}
+
+function replaceTextBlocks(
+  value: unknown,
+  transform: (text: string) => string,
+): unknown {
+  if (typeof value === "string") return transform(value);
+  if (!Array.isArray(value)) return value;
+
+  let changed = false;
+  const next = value.map((entry) => {
+    if (!isRecord(entry) || typeof (entry as TextBlock).text !== "string") {
+      return entry;
+    }
+    const text = transform((entry as TextBlock).text as string);
+    if (text === (entry as TextBlock).text) return entry;
+    changed = true;
+    return { ...entry, text };
+  });
+  return changed ? next : value;
+}
+
+function replaceMessageContent(
+  messages: unknown,
+  transform: (text: string) => string,
+): unknown {
+  if (!Array.isArray(messages)) return messages;
+  let changed = false;
+  const next = messages.map((entry) => {
+    if (!isRecord(entry)) return entry;
+    const message = entry as MessageLike;
+    if (message.role !== "system" && message.role !== "developer") return entry;
+    let nextMessage: MessageLike = message;
+    const content = replaceTextBlocks(message.content, transform);
+    if (content !== message.content) nextMessage = { ...nextMessage, content };
+    if (message.role === "system" && isRecord(message.sections)) {
+      let sectionsChanged = false;
+      const sections = Object.fromEntries(Object.entries(message.sections).map(([name, value]) => {
+        if (typeof value !== "string") return [name, value];
+        const text = transform(value);
+        if (text !== value) sectionsChanged = true;
+        return [name, text];
+      }));
+      if (sectionsChanged) nextMessage = { ...nextMessage, sections };
+    }
+    if (message.role === "system" && Array.isArray(message.toolsAdded)) {
+      const toolsAdded = replaceToolDescriptions(message.toolsAdded, transform);
+      if (toolsAdded !== message.toolsAdded) nextMessage = { ...nextMessage, toolsAdded };
+    }
+    if (nextMessage === message) return entry;
+    changed = true;
+    return nextMessage;
+  });
+  return changed ? next : messages;
+}
+
+function replaceTranscriptContext(
+  value: unknown,
+  transform: (text: string) => string,
+): unknown {
+  if (!isRecord(value)) return value;
+  const messages = replaceMessageContent(value.messages, transform);
+  return messages === value.messages ? value : { ...value, messages };
+}
+
+function replaceToolDescriptions(
+  tools: unknown,
+  transform: (text: string) => string,
+): unknown {
+  if (!Array.isArray(tools)) return tools;
+  let changed = false;
+  const next = tools.map((entry) => {
+    if (!isRecord(entry)) return entry;
+    const tool = entry as ToolLike;
+    let nextTool: ToolLike = tool;
+    if (typeof tool.description === "string") {
+      const description = transform(tool.description);
+      if (description !== tool.description) {
+        nextTool = { ...nextTool, description };
+      }
+    }
+    if (isRecord(tool.function) && typeof tool.function.description === "string") {
+      const description = transform(tool.function.description);
+      if (description !== tool.function.description) {
+        nextTool = {
+          ...nextTool,
+          function: { ...tool.function, description },
+        };
+      }
+    }
+    if (nextTool === tool) return entry;
+    changed = true;
+    return nextTool;
+  });
+  return changed ? next : tools;
+}
+
+function replaceSystemInstruction(
+  value: unknown,
+  transform: (text: string) => string,
+): unknown {
+  if (typeof value === "string" || Array.isArray(value)) {
+    return replaceTextBlocks(value, transform);
+  }
+  if (!isRecord(value)) return value;
+  const parts = replaceTextBlocks(value.parts, transform);
+  if (parts === value.parts) return value;
+  return { ...value, parts };
+}
+
+function uniqueInOrder(values: Iterable<string>): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const value of values) {
+    if (!value || seen.has(value)) continue;
+    seen.add(value);
+    result.push(value);
+  }
+  return result;
+}
+
+export function optimizePayload<T>(
+  payload: T,
+  config: OptimizeConfig,
+): OptimizeResult<T> {
+  if (!isRecord(payload)) {
+    return {
+      next: payload,
+      removedChars: 0,
+      baseRemovedChars: 0,
+      addedPrefetchChars: 0,
+      selected: [],
+      catalogNames: [],
+      fingerprints: [],
+      budget: emptyBudget(config),
+    };
+  }
+
+  const originalLength = serializedLength(payload);
+  const query = extractRequestQuery(normalizeRequest(payload));
+  const source = payload as PayloadLike;
+  const catalogSkills: Skill[] = [];
+  const catalogSkillNames = new Set<string>();
+  const catalogNames: string[] = [];
+  const fingerprints: string[] = [];
+  const budget = emptyBudget(config);
+  let baseRemovedChars = 0;
+  const catalogFloors: number[] = [];
+  const inspect = (text: string): string => {
+    const preview = inspectStableSkillCatalog(text, {
+      never: config.excludeSkills,
+      intentMaxChars: config.intentMaxChars,
+    });
+    if (preview.skills.length > 0) catalogFloors.push(preview.floorChars);
+    return text;
+  };
+  replaceTextBlocks(source.system, inspect);
+  replaceSystemInstruction(source.systemInstruction, inspect);
+  if (typeof source.instructions === "string") inspect(source.instructions);
+  replaceMessageContent(source.messages, inspect);
+  replaceMessageContent(source.input, inspect);
+  replaceTranscriptContext(source.context, inspect);
+  replaceToolDescriptions(source.tools, inspect);
+
+  let catalogIndex = 0;
+  let remainingIntentBudget = Math.max(
+    0,
+    config.catalogBudgetChars -
+      catalogFloors.reduce((sum, floor) => sum + floor, 0),
+  );
+
+  const transform = (text: string): string => {
+    const floorChars = catalogFloors[catalogIndex] ?? 0;
+    const result = renderStableSkillCatalog(text, {
+      never: config.excludeSkills,
+      intentMaxChars: config.intentMaxChars,
+      budgetChars: floorChars + remainingIntentBudget,
+    });
+    if (result.skills.length === 0) return text;
+
+    catalogIndex += 1;
+    remainingIntentBudget = Math.max(
+      0,
+      remainingIntentBudget - Math.max(0, result.budget.usedChars - floorChars),
+    );
+    baseRemovedChars += result.removedChars;
+    catalogNames.push(...result.skills.map((skill) => skill.name));
+    fingerprints.push(result.fingerprint);
+    mergeBudget(budget, result.budget);
+
+    for (const skill of result.skills) {
+      if (catalogSkillNames.has(skill.name)) continue;
+      catalogSkillNames.add(skill.name);
+      catalogSkills.push(skill);
+    }
+    return result.text;
+  };
+
+  let next: PayloadLike = source;
+
+  const system = replaceTextBlocks(source.system, transform);
+  if (system !== source.system) next = { ...next, system };
+
+  const systemInstruction = replaceSystemInstruction(
+    source.systemInstruction,
+    transform,
+  );
+  if (systemInstruction !== source.systemInstruction) {
+    next = { ...next, systemInstruction };
+  }
+
+  if (typeof source.instructions === "string") {
+    const instructions = transform(source.instructions);
+    if (instructions !== source.instructions) next = { ...next, instructions };
+  }
+
+  const messages = replaceMessageContent(source.messages, transform);
+  if (messages !== source.messages) next = { ...next, messages };
+
+  const input = replaceMessageContent(source.input, transform);
+  if (input !== source.input) next = { ...next, input };
+
+  const context = replaceTranscriptContext(source.context, transform);
+  if (context !== source.context) next = { ...next, context };
+
+  const tools = replaceToolDescriptions(source.tools, transform);
+  if (tools !== source.tools) next = { ...next, tools };
+
+  budget.overBudgetChars = Math.max(
+    budget.overBudgetChars,
+    Math.max(0, budget.usedChars - config.catalogBudgetChars),
+  );
+
+  if (next === source || budget.catalogs === 0) {
+    return {
+      next: payload,
+      removedChars: 0,
+      baseRemovedChars: 0,
+      addedPrefetchChars: 0,
+      selected: [],
+      catalogNames: uniqueInOrder(catalogNames),
+      fingerprints: uniqueInOrder(fingerprints),
+      budget,
+    };
+  }
+
+  let addedPrefetchChars = 0;
+  const selectedSkills =
+    planSkillPrefetch(catalogSkills, query, {
+      profile: config.profile,
+      usagePrior: config.usagePrior,
+      always: uniqueInOrder([
+        ...(config.profile?.critical ?? []),
+        ...(config.alwaysSkills ?? []),
+      ]),
+      never: config.excludeSkills,
+      targetTopK: config.prefetchTarget,
+      minTopK: config.prefetchMin,
+      maxTopK: config.prefetchMax,
+      fullRenderBudgetChars: config.prefetchBudgetChars,
+      fuzzyCandidateLimit: config.fuzzyCandidateLimit,
+    }).selected;
+  if (selectedSkills.length > 0) {
+    const appendix = renderSkillPrefetch({
+      selected: selectedSkills,
+    } as Parameters<typeof renderSkillPrefetch>[0]);
+    if (appendix) {
+      const withPrefetch = appendToLatestHumanInput(
+        next,
+        appendix,
+        PREFETCH_MARKER,
+      ) as PayloadLike;
+      if (withPrefetch !== next) {
+        addedPrefetchChars = serializedLength(withPrefetch) - serializedLength(next);
+        next = withPrefetch;
+      }
+    }
+  }
+
+  const finalLength = serializedLength(next);
+  if (
+    !Number.isFinite(originalLength) ||
+    !Number.isFinite(finalLength) ||
+    finalLength >= originalLength
+  ) {
+    return {
+      next: payload,
+      removedChars: 0,
+      baseRemovedChars: 0,
+      addedPrefetchChars: 0,
+      selected: [],
+      catalogNames: uniqueInOrder(catalogNames),
+      fingerprints: uniqueInOrder(fingerprints),
+      budget,
+    };
+  }
+
+  return {
+    next: next as T,
+    removedChars: originalLength - finalLength,
+    baseRemovedChars,
+    addedPrefetchChars: Math.max(0, addedPrefetchChars),
+    selected: selectedSkills.map((skill) => skill.name),
+    catalogNames: uniqueInOrder(catalogNames),
+    fingerprints: uniqueInOrder(fingerprints),
+    budget,
+  };
+}

package/src/output-recovery.ts

@@ -0,0 +1,19 @@
+/** Slice original text offsets, retaining every selected line's original terminator. */
+export function sliceOutputLines(text: string, startLine = 1, lineCount = 200): {
+	text: string; startLine: number; lineCount: number; totalLines: number;
+} {
+	if (!Number.isSafeInteger(startLine) || startLine < 1) {
+		throw new RangeError("startLine must be a positive safe integer");
+	}
+	if (!Number.isSafeInteger(lineCount) || lineCount < 1 || lineCount > 1000) {
+		throw new RangeError("lineCount must be an integer from 1 to 1000");
+	}
+	const starts = [0];
+	for (const match of text.matchAll(/\r\n|\n|\r/g)) starts.push(match.index + match[0].length);
+	const totalLines = starts.length;
+	if (startLine > totalLines) return { text: "", startLine, lineCount: 0, totalLines };
+	const count = Math.min(lineCount, totalLines - startLine + 1);
+	const from = starts[startLine - 1];
+	const to = starts[startLine - 1 + count] ?? text.length;
+	return { text: text.slice(from, to), startLine, lineCount: count, totalLines };
+}