@jameslovespancakes/pi-plus 1.0.11 → 1.0.12

package/src/domains/workflows/runtime/agent-session.ts

@@ -0,0 +1,382 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import {
+  createAgentSessionFromServices,
+  createAgentSessionServices,
+  defineTool,
+  SessionManager,
+  type CreateAgentSessionOptions,
+  type ModelRegistry,
+  type Skill,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { prepareAgentSkillResources } from "./agent-skills.ts";
+import type {
+  AgentExecutionOptions,
+  AgentRunTags,
+  AgentRunnerSession,
+  RunContext,
+} from "./agent-runner-types.ts";
+import { raceWithAbort, throwIfAborted } from "./cancellation.ts";
+import {
+  MAX_SCHEMA_REPAIR_ATTEMPTS,
+  WorkflowStructuredOutputError,
+} from "./structured-output.ts";
+import { providerErrorFromMessages } from "./agent-retry.ts";
+import { synchronizeWorkflowModelRuntime } from "./agent-session-providers.ts";
+import { matchesAgentToolHint, WorkflowToolHintUnavailableError } from "./tool-capabilities.ts";
+import type { AgentToolHint } from "./types.ts";
+
+export const FINAL_TOOL = "final_answer";
+
+const SCHEMA_REPROMPT =
+  `You ended your turn without calling the ${FINAL_TOOL} tool, so no result was recorded. ` +
+  `Call ${FINAL_TOOL} now with your final answer as its arguments. Do not reply with plain text.`;
+const DEFAULT_SEARCH_BASE_TOOLS = ["read", "bash", "grep", "find", "ls"];
+
+export interface ResolvedAgentModelRequest {
+  readonly ref: string;
+  readonly provider: string;
+  readonly id: string;
+}
+
+export interface ResolvedAgentModel {
+  readonly model: Model<Api> | undefined;
+  readonly requested: ResolvedAgentModelRequest | undefined;
+}
+
+export interface AgentSessionHandle {
+  readonly session: AgentRunnerSession;
+  readonly selectedSkills: readonly Skill[];
+  hasStructuredResult(): boolean;
+  structuredResult(): unknown;
+}
+
+export function resolveAgentModel(
+  modelRef: string | undefined,
+  modelRegistry: Pick<ModelRegistry, "find">,
+  hostModel: Model<Api> | undefined,
+): ResolvedAgentModel {
+  if (modelRef === undefined) return { model: hostModel, requested: undefined };
+
+  const parsed = parseAgentModelRef(modelRef);
+  const found = modelRegistry.find(parsed.provider, parsed.id);
+  if (!found) {
+    throw new Error(`Agent model "${modelRef}" not found (resolved as ${parsed.provider}/${parsed.id}).`);
+  }
+  return { model: found, requested: parsed };
+}
+
+export async function openAgentSession(input: {
+  readonly rc: RunContext;
+  readonly prompt: string;
+  readonly opts: AgentExecutionOptions;
+  readonly cwd: string;
+  readonly model: Model<Api> | undefined;
+  readonly label: string;
+  readonly tags: AgentRunTags;
+}): Promise<AgentSessionHandle> {
+  const { rc, prompt, opts, cwd, model, label, tags } = input;
+  let captured = false;
+  let structuredResult: unknown;
+  const customTools: ToolDefinition[] = opts.schema
+    ? [
+        defineTool({
+          name: FINAL_TOOL,
+          label: "Final Answer",
+          description:
+            "Return your final structured answer. This MUST be your last action — do not write a normal reply after calling it.",
+          parameters: opts.schema,
+          async execute(_toolCallId, params) {
+            captured = true;
+            structuredResult = params;
+            return { content: [{ type: "text", text: "Recorded." }], details: params, terminate: true };
+          },
+        }),
+      ]
+    : [];
+  let session: AgentRunnerSession | undefined;
+  try {
+    throwIfAborted(rc.signal);
+    const resourceInput = { rc, prompt, opts, cwd, model, customTools, label };
+    const resources = rc.createSession
+      ? await prepareAgentSessionResources(resourceInput)
+      : await rc.perf.time(
+          "agent.session_resources_ms",
+          () => prepareAgentSessionResources(resourceInput),
+          tags,
+        );
+    const toolSelection = buildToolSelection(opts, resources.selectedSkills.length > 0);
+    session = (
+      await rc.perf.time(
+        "agent.create_session_ms",
+        () => resources.createSession(toolSelection.sessionOptions),
+        tags,
+      )
+    ).session;
+    session.setAutoRetryEnabled(false);
+    const matchedToolHints = toolSelection.toolHints.length === 0
+      ? new Set<AgentToolHint>()
+      : applyDynamicToolHints(session, toolSelection);
+    if (opts.requireToolHints) {
+      const missing = toolSelection.toolHints.filter((hint) => !matchedToolHints.has(hint));
+      if (missing.length > 0) throw new WorkflowToolHintUnavailableError(missing);
+    }
+    throwIfAborted(rc.signal);
+    return {
+      session,
+      selectedSkills: resources.selectedSkills,
+      hasStructuredResult: () => captured,
+      structuredResult: () => structuredResult,
+    };
+  } catch (error) {
+    if (session) {
+      const activeSession = session;
+      session = undefined;
+      rc.perf.timeSync("agent.dispose_ms", () => activeSession.dispose(), tags);
+    }
+    throw error;
+  }
+}
+
+export async function promptAgentSession(input: {
+  readonly rc: RunContext;
+  readonly handle: AgentSessionHandle;
+  readonly prompt: string;
+  readonly opts: AgentExecutionOptions;
+  readonly label: string;
+  readonly rowId: number;
+  readonly tags: AgentRunTags;
+}): Promise<unknown> {
+  const { rc, handle, prompt, opts, label, rowId, tags } = input;
+  const { session } = handle;
+  const unbindFollowUp = rc.progress.bindAgentFollowUp(rowId, async (message) => {
+    if (!session.isStreaming) throw new Error("This agent has already finished its current turn.");
+    await session.followUp(message);
+  });
+  const unsubscribe = session.subscribe((event) => {
+    if (event.type === "tool_execution_start" && event.toolName !== undefined && event.toolName !== FINAL_TOOL) {
+      rc.progress.agentTool(label, event.toolName, rowId);
+      return;
+    }
+    if (event.type === "message_end" && event.message.role === "assistant") {
+      const text = event.message.content
+        .filter((part) => part.type === "text")
+        .map((part) => part.text)
+        .join("\n")
+        .trim();
+      if (text) rc.progress.agentMessage(rowId, "assistant", text);
+    }
+  });
+
+  try {
+    const finalPrompt = opts.schema
+      ? `${prompt}\n\nWhen finished, return your result by calling the ${FINAL_TOOL} tool.`
+      : prompt;
+    throwIfAborted(rc.signal);
+    const unlinkPromptAbort = linkSessionAbort(rc.signal, session);
+    try {
+      try {
+        const promptSession = async (text: string) => {
+          await rc.perf.time("agent.prompt_ms", () => raceWithAbort(() => session.prompt(text), rc.signal), tags);
+          const failure = providerErrorFromMessages(session.messages, {
+            pauseOnUsageLimit: rc.pauseOnProviderUsageLimit,
+          });
+          if (failure) throw failure;
+        };
+        await promptSession(finalPrompt);
+        if (opts.schema) {
+          for (let attempt = 0; !handle.hasStructuredResult() && attempt < MAX_SCHEMA_REPAIR_ATTEMPTS; attempt++) {
+            throwIfAborted(rc.signal);
+            session.setActiveToolsByName([FINAL_TOOL]);
+            rc.progress.log(`${label}: no final answer; re-prompting (${attempt + 1}/${MAX_SCHEMA_REPAIR_ATTEMPTS})`);
+            rc.perf.counter("agent.structured_reprompt", 1, tags);
+            await promptSession(SCHEMA_REPROMPT);
+          }
+        }
+
+        throwIfAborted(rc.signal);
+        return rc.perf.timeSync(
+          "agent.extract_result_ms",
+          () => {
+            if (!opts.schema) {
+              return session.getLastAssistantText() ?? "";
+            }
+            if (!handle.hasStructuredResult()) {
+              rc.progress.log(`${label}: no structured answer returned`);
+              rc.perf.counter("agent.structured_missing", 1, tags);
+              throw new WorkflowStructuredOutputError(label, MAX_SCHEMA_REPAIR_ATTEMPTS);
+            }
+            return handle.structuredResult();
+          },
+          tags,
+        );
+      } finally {
+        rc.usage.recordAgentSession({ label, phase: tags.phase, messages: session.messages });
+      }
+    } finally {
+      unlinkPromptAbort();
+    }
+  } finally {
+    unbindFollowUp();
+    unsubscribe();
+  }
+}
+
+function parseAgentModelRef(modelRef: string): ResolvedAgentModelRequest {
+  const normalized = modelRef.trim();
+  if (normalized.length === 0) {
+    throw new Error('Invalid agent model ref: expected a bare model id or "provider/id".');
+  }
+  if (normalized !== modelRef) {
+    throw new Error(`Invalid agent model ref "${modelRef}": remove leading or trailing whitespace.`);
+  }
+
+  const slash = modelRef.indexOf("/");
+  if (slash === -1) return { ref: modelRef, provider: "anthropic", id: modelRef };
+  const provider = modelRef.slice(0, slash);
+  const id = modelRef.slice(slash + 1);
+  if (provider.length === 0 || id.length === 0 || id.startsWith("/")) {
+    throw new Error(`Invalid agent model ref "${modelRef}": expected "provider/id".`);
+  }
+  return { ref: modelRef, provider, id };
+}
+
+interface AgentSessionResources {
+  readonly selectedSkills: readonly Skill[];
+  createSession(sessionOptions: ToolSessionOptions): Promise<{ session: AgentRunnerSession }>;
+}
+
+async function prepareAgentSessionResources(input: {
+  readonly rc: RunContext;
+  readonly prompt: string;
+  readonly opts: AgentExecutionOptions;
+  readonly cwd: string;
+  readonly model: Model<Api> | undefined;
+  readonly customTools: ToolDefinition[];
+  readonly label: string;
+}): Promise<AgentSessionResources> {
+  const { rc, prompt, opts, cwd, model, customTools, label } = input;
+  const commonSessionOptions = (sessionOptions: ToolSessionOptions) => ({
+    model,
+    thinkingLevel: opts.thinkingLevel,
+    noTools: sessionOptions.noTools,
+    tools: sessionOptions.tools,
+    customTools,
+    sessionManager: SessionManager.inMemory(cwd),
+  });
+  const createSession = rc.createSession;
+  if (createSession) {
+    return {
+      selectedSkills: [],
+      createSession: (sessionOptions) =>
+        createSession({
+          cwd,
+          ...commonSessionOptions(sessionOptions),
+        }),
+    };
+  }
+
+  const skillOptions = {
+    prompt,
+    skills: opts.skills,
+    log: (message: string) => rc.progress.log(`${label}: ${message}`),
+  };
+  const preparedSkills = prepareAgentSkillResources(skillOptions);
+  const services = await createAgentSessionServices({
+    cwd,
+    resourceLoaderOptions: preparedSkills.resourceLoaderOptions,
+  });
+  await synchronizeWorkflowModelRuntime({
+    host: rc.modelRegistry,
+    child: services.modelRuntime,
+    selectedModel: model,
+    // Shared-cwd sessions mirror live removals; isolated cwd sessions retain target-only providers.
+    removeChildOnlyProviders: cwd === rc.cwd,
+  });
+  for (const diagnostic of services.diagnostics) {
+    rc.progress.log(`${label}: session ${diagnostic.type}: ${diagnostic.message}`);
+  }
+  const selectedSkills = preparedSkills.resolve(services.resourceLoader);
+  return {
+    selectedSkills,
+    createSession: (sessionOptions) =>
+      createAgentSessionFromServices({
+        services,
+        ...commonSessionOptions(sessionOptions),
+      }),
+  };
+}
+
+function linkSessionAbort(signal: AbortSignal | undefined, session: AgentRunnerSession): () => void {
+  if (!signal) return () => {};
+  const onAbort = () => {
+    void session.abort().catch(() => undefined);
+  };
+  if (signal.aborted) {
+    onAbort();
+    return () => {};
+  }
+  signal.addEventListener("abort", onAbort, { once: true });
+  return () => signal.removeEventListener("abort", onAbort);
+}
+
+type ToolSessionOptions = Pick<CreateAgentSessionOptions, "tools" | "noTools">;
+
+interface ToolSelection {
+  readonly sessionOptions: ToolSessionOptions;
+  readonly activeTools?: readonly string[];
+  readonly toolHints: NonNullable<AgentExecutionOptions["toolHints"]>;
+}
+
+function buildToolSelection(opts: AgentExecutionOptions, skillsEnabled: boolean): ToolSelection {
+  const toolHints = opts.toolHints ?? [];
+  const fallback = toolHints.includes("search")
+    ? DEFAULT_SEARCH_BASE_TOOLS
+    : toolHints.includes("external-search")
+      ? ["read"]
+      : undefined;
+  const activeTools = buildToolList(opts, skillsEnabled, fallback);
+  if (toolHints.length === 0) {
+    return {
+      sessionOptions: { tools: activeTools ? [...activeTools] : undefined },
+      activeTools,
+      toolHints,
+    };
+  }
+
+  return {
+    sessionOptions: { noTools: "builtin" },
+    activeTools,
+    toolHints,
+  };
+}
+
+function buildToolList(
+  opts: AgentExecutionOptions,
+  skillsEnabled: boolean,
+  fallback?: readonly string[],
+): string[] | undefined {
+  const configured = opts.tools ?? fallback;
+  const allow = configured ? [...configured] : undefined;
+  if (!allow) return undefined;
+  if (skillsEnabled && !allow.includes("read")) allow.push("read");
+  if (opts.schema && !allow.includes(FINAL_TOOL)) allow.push(FINAL_TOOL);
+  return allow;
+}
+
+function applyDynamicToolHints(
+  session: AgentRunnerSession,
+  selection: ToolSelection,
+): ReadonlySet<AgentToolHint> {
+  const active = new Set(selection.activeTools ?? []);
+  const matched = new Set<AgentToolHint>();
+  for (const tool of session.getAllTools()) {
+    for (const hint of selection.toolHints) {
+      if (!matchesAgentToolHint(tool, hint)) continue;
+      matched.add(hint);
+      active.add(tool.name);
+    }
+  }
+  session.setActiveToolsByName([...active]);
+  return matched;
+}

package/src/domains/workflows/runtime/agent-skills.ts

@@ -0,0 +1,270 @@
+import type {
+  CreateAgentSessionServicesOptions,
+  ResourceDiagnostic,
+  ResourceLoader,
+  Skill,
+} from "@earendil-works/pi-coding-agent";
+import { dirname, resolve } from "node:path";
+import { logicalWorkspacePath, type ReplayWorkspaceRoots } from "./replay-path-identity.ts";
+import { captureTreeFingerprint } from "./tree-fingerprint.ts";
+import type { ResolvedSkillIdentity } from "./resume-context.ts";
+
+interface AgentSkillRequest {
+  readonly selectors: readonly string[];
+  readonly strict: boolean;
+}
+
+export interface AgentSkillResolution {
+  readonly selected: readonly Skill[];
+  readonly unmatched: readonly string[];
+}
+
+type AgentSkillResourceLoaderOptions = Pick<
+  NonNullable<CreateAgentSessionServicesOptions["resourceLoaderOptions"]>,
+  "noSkills" | "skillsOverride"
+>;
+
+interface PreparedAgentSkillResources {
+  readonly resourceLoaderOptions: AgentSkillResourceLoaderOptions;
+  resolve(resourceLoader: Pick<ResourceLoader, "getSkills">): readonly Skill[];
+}
+
+export type AgentSkillIdentityCapture =
+  | { readonly kind: "verified"; readonly skills: readonly ResolvedSkillIdentity[] }
+  | { readonly kind: "unverifiable"; readonly reason: string };
+
+export interface AgentSkillIdentityOptions extends ReplayWorkspaceRoots {
+  readonly signal?: AbortSignal;
+}
+
+const SKILL_FINGERPRINT_EXCLUSIONS = new Set([".git", "node_modules"]);
+const SKILL_FINGERPRINT_MAX_BYTES = 8 << 20;
+const SKILL_FINGERPRINT_MAX_FILES = 1024;
+
+const SLASH_SKILL_PATTERN = /\/skill:([a-z0-9][a-z0-9-]{0,63})/gi;
+const SKILLS_FIELD_PATTERN = /(?<!\/)\bskills?\s*[:=]\s*([^\n.;]+)/gi;
+const VERB_SKILL_LIST_PATTERN = /\b(?:include|use|enable|load|provide|allow|grant|with)\s+(?:the\s+|this\s+|these\s+)?skills?\s+([^\n.;]+)/gi;
+const VERB_NAMED_SKILL_PATTERN = /\b(?:include|use|enable|load|provide|allow|grant|with)\s+(?:the\s+|this\s+|these\s+)?(["'`]?)([a-z0-9][a-z0-9 _-]{0,80}?)\1\s+skills?\b/gi;
+const PURPOSE_BOUNDARY_PATTERN = /\s+\b(?:for|to|when|while|so|because|in\s+order\s+to)\b.*$/i;
+
+/**
+ * Resolve which subagent skills were requested.
+ *
+ * Subagents are skillless by default. Explicit `opts.skills` wins and suppresses prompt inference;
+ * when it is omitted we only infer from clear natural-language opt-ins such as `/skill:name`,
+ * `include skill diagnose`, `include this Skill diagnose`, or `use the diagnose skill`.
+ */
+export function resolveAgentSkillRequest(prompt: string, explicitSkills: unknown): AgentSkillRequest {
+  if (explicitSkills !== undefined) {
+    return { selectors: normalizeExplicitSkillSelectors(explicitSkills), strict: true };
+  }
+  return { selectors: extractSkillSelectorsFromText(prompt), strict: false };
+}
+
+export function extractSkillSelectorsFromText(text: string): string[] {
+  const selectors: string[] = [];
+  collectPatternMatches(text, SLASH_SKILL_PATTERN, selectors, 1);
+  collectListPatternMatches(text, SKILLS_FIELD_PATTERN, selectors);
+  collectListPatternMatches(text, VERB_SKILL_LIST_PATTERN, selectors);
+  collectPatternMatches(text, VERB_NAMED_SKILL_PATTERN, selectors, 2);
+  return uniqueSelectors(selectors);
+}
+
+export function normalizeSkillSelector(value: string): string {
+  return value
+    .trim()
+    .replace(/^\/skill:/i, "")
+    .replace(/^skills?\s*[:=]?\s*/i, "")
+    .replace(/^(?:named|called)\s+/i, "")
+    .replace(/^(?:the|this|these)\s+/i, "")
+    .replace(/\s+skills?$/i, "")
+    .replace(/^[`"']+|[`"']+$/g, "")
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, "-")
+    .replace(/[^a-z0-9-]/g, "")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+export function selectAgentSkills(skills: readonly Skill[], selectors: readonly string[]): AgentSkillResolution {
+  const selected = new Map<string, Skill>();
+  const unmatched: string[] = [];
+
+  for (const selector of selectors) {
+    const match = matchSkillSelector(skills, selector);
+    if (!match) {
+      unmatched.push(selector);
+      continue;
+    }
+    selected.set(match.name, makeSkillModelInvocable(match));
+  }
+
+  return { selected: [...selected.values()], unmatched };
+}
+
+/**
+ * Prepare the skill-selection hooks consumed by pi's session-service factory.
+ * The returned resolver is scoped to one resource loader and must not be reused
+ * across concurrently-created session services.
+ */
+export function prepareAgentSkillResources(options: {
+  readonly prompt: string;
+  readonly skills: unknown;
+  readonly log?: (message: string) => void;
+}): PreparedAgentSkillResources {
+  const request = resolveAgentSkillRequest(options.prompt, options.skills);
+  let resolution: AgentSkillResolution = { selected: [], unmatched: [] };
+  let availableSkillNames: readonly string[] = [];
+
+  const resourceLoaderOptions: AgentSkillResourceLoaderOptions = {
+    noSkills: request.selectors.length === 0,
+    skillsOverride:
+      request.selectors.length === 0
+        ? undefined
+        : (current) => {
+            availableSkillNames = current.skills.map((skill) => skill.name).sort();
+            resolution = selectAgentSkills(current.skills, request.selectors);
+            return { skills: [...resolution.selected], diagnostics: current.diagnostics };
+          },
+  };
+
+  return {
+    resourceLoaderOptions,
+    resolve(resourceLoader) {
+      const { diagnostics } = resourceLoader.getSkills();
+      logSkillDiagnostics(options.log, diagnostics, request.selectors.length > 0);
+
+      if (request.strict && resolution.unmatched.length > 0) {
+        throw new Error(
+          `Unknown subagent skill${resolution.unmatched.length === 1 ? "" : "s"}: ${resolution.unmatched.join(", ")}. Available: ${
+            availableSkillNames.join(", ") || "(none)"
+          }.`,
+        );
+      }
+
+      if (!request.strict && resolution.unmatched.length > 0) {
+        options.log?.(`Ignoring unrecognized subagent skill mention${resolution.unmatched.length === 1 ? "" : "s"}: ${resolution.unmatched.join(", ")}`);
+      }
+
+      return resolution.selected;
+    },
+  };
+}
+
+/** Capture the exact selected skill directories before journal lookup. */
+export async function captureAgentSkillIdentities(
+  skills: readonly Skill[],
+  options: AgentSkillIdentityOptions,
+): Promise<AgentSkillIdentityCapture> {
+  const identities: ResolvedSkillIdentity[] = [];
+  for (const skill of skills) {
+    const root = resolve(dirname(skill.filePath));
+    const capture = await captureTreeFingerprint({
+      root,
+      excludedRelativePaths: SKILL_FINGERPRINT_EXCLUSIONS,
+      maxBytes: SKILL_FINGERPRINT_MAX_BYTES,
+      maxFiles: SKILL_FINGERPRINT_MAX_FILES,
+      signal: options.signal,
+    });
+    if (capture.kind === "unverifiable") {
+      return { kind: "unverifiable", reason: `skill ${skill.name} could not be fingerprinted: ${capture.reason}` };
+    }
+    identities.push({
+      name: skill.name,
+      path: logicalWorkspacePath(root, options) ?? `external:${skill.name}`,
+      fingerprint: capture.fingerprint,
+    });
+  }
+  return { kind: "verified", skills: identities };
+}
+
+function collectPatternMatches(text: string, pattern: RegExp, selectors: string[], captureIndex: number): void {
+  pattern.lastIndex = 0;
+  for (let match = pattern.exec(text); match !== null; match = pattern.exec(text)) {
+    const value = match[captureIndex];
+    if (value !== undefined) selectors.push(value);
+  }
+}
+
+function collectListPatternMatches(text: string, pattern: RegExp, selectors: string[]): void {
+  pattern.lastIndex = 0;
+  for (let match = pattern.exec(text); match !== null; match = pattern.exec(text)) {
+    const value = match[1];
+    if (value === undefined) continue;
+    selectors.push(...parseSkillList(value));
+  }
+}
+
+function parseSkillList(fragment: string): string[] {
+  const scoped = fragment.replace(PURPOSE_BOUNDARY_PATTERN, "");
+  return scoped
+    .split(/\s*(?:,|\s+\band\b\s+|&|\+)\s*/i)
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+}
+
+function normalizeExplicitSkillSelectors(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    throw new Error("Invalid subagent skills option: expected an array of skill names.");
+  }
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const item of value) {
+    if (typeof item !== "string") {
+      throw new Error("Invalid subagent skills option: every skill name must be a string.");
+    }
+    const normalized = normalizeSkillSelector(item);
+    if (!normalized || isGenericSkillWord(normalized)) {
+      throw new Error(`Invalid subagent skills option: "${item}" is not a valid skill name.`);
+    }
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+    result.push(normalized);
+  }
+  return result;
+}
+
+function logSkillDiagnostics(log: ((message: string) => void) | undefined, diagnostics: readonly ResourceDiagnostic[], requested: boolean): void {
+  if (!requested || !log) return;
+  for (const diagnostic of diagnostics) {
+    const where = diagnostic.path ? ` (${diagnostic.path})` : "";
+    log(`skill ${diagnostic.type}: ${diagnostic.message}${where}`);
+  }
+}
+
+function uniqueSelectors(values: Iterable<string>): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const value of values) {
+    const normalized = normalizeSkillSelector(value);
+    if (!normalized || isGenericSkillWord(normalized) || seen.has(normalized)) continue;
+    seen.add(normalized);
+    result.push(normalized);
+  }
+  return result;
+}
+
+function isGenericSkillWord(value: string): boolean {
+  return value === "skill" || value === "skills" || value === "the" || value === "this" || value === "these" || value === "that";
+}
+
+function matchSkillSelector(skills: readonly Skill[], selector: string): Skill | undefined {
+  const normalized = normalizeSkillSelector(selector);
+  if (!normalized) return undefined;
+
+  const exact = skills.find((skill) => skill.name.toLowerCase() === normalized);
+  if (exact) return exact;
+
+  const selectorWords = normalized.replace(/-/g, " ");
+  const fuzzy = skills.filter((skill) => {
+    const name = skill.name.toLowerCase();
+    const words = name.replace(/-/g, " ");
+    return name.includes(normalized) || words.includes(selectorWords);
+  });
+  return fuzzy.length === 1 ? fuzzy[0] : undefined;
+}
+
+function makeSkillModelInvocable(skill: Skill): Skill {
+  return skill.disableModelInvocation ? { ...skill, disableModelInvocation: false } : skill;
+}