@jameslovespancakes/pi-plus 1.0.11 → 1.0.12

package/src/domains/workflows/runtime/journal.ts

@@ -0,0 +1,313 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readdir, readFile, rm, stat, appendFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import type { AgentOptions } from "./types.ts";
+import type { WorktreeBaseline } from "./worktree.ts";
+import { canonicalizeIdentity } from "./identity-canonicalization.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+import {
+  isAgentResumeContext,
+  resumeContextMismatchReason,
+  type AgentResumeContext,
+  type ResumeContextComparisonOptions,
+} from "./resume-context.ts";
+
+export const WORKFLOW_RUNS_DIR = join(".pi", ".workflow-runs");
+
+/**
+ * Run records and replay journals live outside the project by default so they
+ * never clutter a working directory. Override with PI_WORKFLOW_RUNS_DIR, or set
+ * it to "project" to restore the legacy `<cwd>/.pi/.workflow-runs` layout.
+ */
+export function workflowRunsDir(cwd: string): string {
+  const configured = process.env.PI_WORKFLOW_RUNS_DIR?.trim();
+  if (configured === "project") return join(cwd, WORKFLOW_RUNS_DIR);
+  const root = configured && configured.length > 0
+    ? configured
+    : join(process.env.PI_AGENT_DIR ?? join(homedir(), ".pi", "agent"), "workflow-runs");
+  const slug = basename(cwd).replace(/[^A-Za-z0-9._-]+/g, "-").slice(0, 40) || "project";
+  const hash = createHash("sha256").update(cwd).digest("hex").slice(0, 8);
+  return join(root, `${slug}-${hash}`);
+}
+export const WORKFLOW_JOURNAL_KEEP = 50;
+
+export interface JournalEntryV2 {
+  readonly version: 2;
+  readonly key: string;
+  readonly result: unknown;
+  readonly identity: AgentResumeContext;
+}
+
+/** Parsed so journals written before effective-session identity can fail closed without aborting resume. */
+export interface LegacyJournalEntryV2 {
+  readonly version: 2;
+  readonly key: string;
+  readonly result: unknown;
+  readonly identity: unknown;
+}
+
+/** Parsed only so resume can explain why an older entry is not replayed. */
+export interface LegacyJournalEntryV1 {
+  readonly version?: 1;
+  readonly key: string;
+  readonly value: unknown;
+  readonly context?: unknown;
+}
+
+export type JournalEntry = LegacyJournalEntryV2 | LegacyJournalEntryV1;
+
+export type JournalLookup = { readonly hit: true; readonly value: unknown } | { readonly hit: false; readonly reason?: string };
+export type JournalRecordResult = { readonly ok: true } | { readonly ok: false; readonly error: string };
+
+export type AgentJournalKeyCapture =
+  | { readonly kind: "verified"; readonly key: string }
+  | { readonly kind: "unverifiable"; readonly reason: string };
+
+export interface WorkflowJournal {
+  lookup(key: string, identity: AgentResumeContext, options?: ResumeContextComparisonOptions): JournalLookup;
+  record(key: string, result: unknown, identity: AgentResumeContext): Promise<JournalRecordResult>;
+}
+
+export class WorkflowJournalLoadError extends Error {
+  override readonly name = "WorkflowJournalLoadError";
+}
+
+export function createWorkflowRunId(): string {
+  return randomUUID();
+}
+
+export function workflowJournalPath(cwd: string, runId: string): string {
+  return join(workflowRunsDir(cwd), `${validateWorkflowRunId(runId)}.jsonl`);
+}
+
+export function agentJournalKey(prompt: string, opts: AgentOptions = {}, worktreeBaseline?: WorktreeBaseline): string {
+  const capture = captureAgentJournalKey(prompt, opts, worktreeBaseline);
+  return capture.kind === "verified" ? capture.key : `agent:unverifiable:${randomUUID()}`;
+}
+
+export function hashAgentCall(prompt: string, opts: AgentOptions = {}, worktreeBaseline?: WorktreeBaseline): string {
+  const capture = captureAgentCallHash(prompt, opts, worktreeBaseline);
+  return capture.kind === "verified"
+    ? capture.hash
+    : createHash("sha256").update(`unverifiable:${randomUUID()}`).digest("hex");
+}
+
+/** Capture a replay key without allowing hostile or oversized schemas to escape as exceptions. */
+export function captureAgentJournalKey(
+  prompt: string,
+  opts: AgentOptions = {},
+  worktreeBaseline?: WorktreeBaseline,
+): AgentJournalKeyCapture {
+  const behavior = captureAgentCallHash(prompt, opts, worktreeBaseline);
+  if (behavior.kind === "unverifiable") return behavior;
+  let cacheKey: string | undefined;
+  try {
+    cacheKey = opts.cacheKey?.trim();
+  } catch {
+    return { kind: "unverifiable", reason: "agent cache key could not be inspected" };
+  }
+  if (!cacheKey) return { kind: "verified", key: `agent:${behavior.hash}` };
+  const cacheKeyHash = createHash("sha256").update(cacheKey).digest("hex");
+  return { kind: "verified", key: `agent:${cacheKeyHash}:${behavior.hash}` };
+}
+
+type AgentCallHashCapture =
+  | { readonly kind: "verified"; readonly hash: string }
+  | { readonly kind: "unverifiable"; readonly reason: string };
+
+function captureAgentCallHash(
+  prompt: string,
+  opts: AgentOptions,
+  worktreeBaseline: WorktreeBaseline | undefined,
+): AgentCallHashCapture {
+  try {
+    const behavior = {
+      prompt,
+      opts: {
+        thinkingLevel: opts.thinkingLevel,
+        tools: opts.tools,
+        toolHints: opts.toolHints,
+        requireToolHints: opts.requireToolHints === true ? true : undefined,
+        skills: opts.skills,
+        schema: opts.schema,
+        isolation: opts.isolation,
+        candidatePatch: opts.candidatePatch
+          ? {
+              baselineOid: opts.candidatePatch.baselineOid,
+              hash: createHash("sha256").update(opts.candidatePatch.patch).digest("hex"),
+            }
+          : undefined,
+        worktreeBaseline: worktreeBaseline
+          ? {
+              ref: worktreeBaseline.ref,
+              patchFingerprint: createHash("sha256").update(worktreeBaseline.patch ?? "").digest("hex"),
+            }
+          : undefined,
+      },
+    };
+    const canonical = canonicalizeIdentity(behavior);
+    return canonical.kind === "verified"
+      ? { kind: "verified", hash: createHash("sha256").update(canonical.value).digest("hex") }
+      : canonical;
+  } catch {
+    return { kind: "unverifiable", reason: "agent replay inputs could not be inspected" };
+  }
+}
+
+export async function loadJournalEntries(path: string, options: { readonly required?: boolean } = {}): Promise<JournalEntry[]> {
+  let content: string;
+  try {
+    content = await readFile(path, "utf8");
+  } catch (error) {
+    if (options.required) {
+      throw new WorkflowJournalLoadError(`Could not load workflow resume journal at ${path}: ${unknownErrorMessage(error)}`);
+    }
+    return [];
+  }
+
+  const entries: JournalEntry[] = [];
+  let lineNumber = 0;
+  for (const line of content.split(/\r?\n/)) {
+    lineNumber += 1;
+    if (line.trim() === "") continue;
+    try {
+      const parsed = JSON.parse(line) as unknown;
+      if (isJournalEntry(parsed)) {
+        entries.push(parsed);
+        continue;
+      }
+      if (options.required) {
+        throw new WorkflowJournalLoadError(`Workflow resume journal at ${path}:${lineNumber} has an incompatible entry format.`);
+      }
+    } catch (error) {
+      if (options.required) {
+        if (error instanceof WorkflowJournalLoadError) throw error;
+        throw new WorkflowJournalLoadError(`Workflow resume journal at ${path}:${lineNumber} is not valid JSON.`);
+      }
+    }
+  }
+  return entries;
+}
+
+export async function createWorkflowJournal(options: {
+  readonly resumePath?: string;
+  readonly writePath: string;
+}): Promise<WorkflowJournal> {
+  const priorEntries = options.resumePath ? await loadJournalEntries(options.resumePath, { required: true }) : [];
+  await mkdir(dirname(options.writePath), { recursive: true });
+  await appendFile(options.writePath, "", "utf8");
+  return createMemoryBackedJournal(priorEntries, options.writePath);
+}
+
+export function createMemoryBackedJournal(priorEntries: readonly JournalEntry[] = [], writePath?: string): WorkflowJournal {
+  const priorByKey = new Map<string, JournalEntry[]>();
+  for (const entry of priorEntries) {
+    const entries = priorByKey.get(entry.key) ?? [];
+    entries.push(entry);
+    priorByKey.set(entry.key, entries);
+  }
+
+  return {
+    lookup(key, identity, options) {
+      const entries = priorByKey.get(key);
+      if (!entries || entries.length === 0) return { hit: false };
+
+      const current = entries.filter(
+        (entry): entry is JournalEntryV2 => entry.version === 2 && isAgentResumeContext(entry.identity),
+      );
+      if (current.length === 0) {
+        return {
+          hit: false,
+          reason: entries.some((entry) => entry.version === 2)
+            ? "journal entry predates effective replay identity"
+            : "journal entry predates replay contract v2",
+        };
+      }
+      const matches = current.filter(
+        (entry) => resumeContextMismatchReason(entry.identity, identity, options) === undefined,
+      );
+      if (matches.length === 1) return { hit: true, value: matches[0]!.result };
+      if (matches.length > 1) return { hit: false, reason: "multiple cached entries match this agent call" };
+      return { hit: false, reason: resumeContextMismatchReason(current[0]!.identity, identity, options) };
+    },
+    async record(key, result, identity) {
+      const entry: JournalEntryV2 = { version: 2, key, result, identity };
+      if (writePath) {
+        try {
+          await mkdir(dirname(writePath), { recursive: true });
+          await appendFile(writePath, `${JSON.stringify(entry)}\n`, "utf8");
+        } catch (error) {
+      return { ok: false, error: unknownErrorMessage(error) };
+        }
+      }
+      return { ok: true };
+    },
+  };
+}
+
+export async function pruneWorkflowJournals(cwd: string, keep = WORKFLOW_JOURNAL_KEEP): Promise<void> {
+  const dir = workflowRunsDir(cwd);
+  let files: string[];
+  try {
+    files = await readdir(dir);
+  } catch {
+    return;
+  }
+
+  const candidates = await Promise.all(
+    files
+      .filter((file) => file.endsWith(".jsonl"))
+      .map(async (file) => {
+        const path = join(dir, file);
+        try {
+          const info = await stat(path);
+          return { path, mtimeMs: info.mtimeMs };
+        } catch {
+          return undefined;
+        }
+      }),
+  );
+
+  const stale = candidates
+    .filter((entry): entry is { readonly path: string; readonly mtimeMs: number } => entry !== undefined)
+    .sort((a, b) => b.mtimeMs - a.mtimeMs)
+    .slice(Math.max(0, keep));
+
+  await Promise.all(stale.map((entry) => rm(entry.path, { force: true }).catch(() => undefined)));
+}
+
+export function validateWorkflowRunId(runId: string): string {
+  const trimmed = runId.trim();
+  if (!/^[A-Za-z0-9_.-]+$/.test(trimmed)) {
+    throw new Error("Workflow run id must contain only letters, numbers, dots, underscores, or hyphens.");
+  }
+  return trimmed;
+}
+
+function isJournalEntry(value: unknown): value is JournalEntry {
+  if (typeof value !== "object" || value === null) return false;
+  const entry = value as {
+    readonly version?: unknown;
+    readonly key?: unknown;
+    readonly result?: unknown;
+    readonly identity?: unknown;
+    readonly value?: unknown;
+    readonly context?: unknown;
+  };
+  if (entry.version === 2) {
+    return typeof entry.key === "string" && "result" in entry && "identity" in entry;
+  }
+  return (
+    (entry.version === undefined || entry.version === 1) &&
+    typeof entry.key === "string" &&
+    "value" in entry &&
+    (entry.context === undefined || isLegacyAgentResumeContext(entry.context))
+  );
+}
+
+function isLegacyAgentResumeContext(value: unknown): boolean {
+  if (typeof value !== "object" || value === null) return false;
+  const context = value as { readonly repository?: unknown; readonly workflow?: unknown; readonly model?: unknown };
+  return "repository" in context && "workflow" in context && "model" in context;
+}

package/src/domains/workflows/runtime/model-profiles.ts

@@ -0,0 +1,310 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { getAgentDir, type ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { isMissingPathError } from "./filesystem-error.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+
+export const WORKFLOW_MODEL_PROFILE_NAMES = ["small", "medium", "big"] as const;
+export type WorkflowModelProfileName = (typeof WORKFLOW_MODEL_PROFILE_NAMES)[number];
+
+export interface WorkflowModelProfileConfig {
+  readonly model: string;
+  readonly thinkingLevel?: ThinkingLevel;
+}
+
+export interface WorkflowModelProfileFile {
+  readonly profiles: Partial<Record<WorkflowModelProfileName, WorkflowModelProfileConfig>>;
+}
+
+export interface WorkflowModelProfilePaths {
+  readonly user: string;
+  readonly project: string;
+}
+
+interface ResolvedWorkflowModelProfileBase {
+  readonly name: WorkflowModelProfileName;
+  readonly model: Model<Api> | undefined;
+  readonly thinkingLevel: ThinkingLevel | undefined;
+}
+
+export type ResolvedWorkflowModelProfile = ResolvedWorkflowModelProfileBase & (
+  | { readonly source: "host" }
+  | { readonly source: "project" | "user"; readonly configPath: string }
+);
+
+export type ResolvedWorkflowModelProfiles = Readonly<Record<WorkflowModelProfileName, ResolvedWorkflowModelProfile>>;
+
+export interface WorkflowModelRouteRequest {
+  readonly model?: string;
+  readonly thinkingLevel?: ThinkingLevel;
+  readonly profile?: WorkflowModelProfileName;
+}
+
+export class WorkflowModelProfileConfigError extends Error {
+  override readonly name = "WorkflowModelProfileConfigError";
+  readonly code = "WORKFLOW_MODEL_PROFILE_CONFIG";
+
+  constructor(
+    message: string,
+    readonly configPath: string,
+    readonly profile?: WorkflowModelProfileName,
+  ) {
+    super(message);
+  }
+}
+
+export const WORKFLOW_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const satisfies readonly ThinkingLevel[];
+const THINKING_LEVELS = new Set<ThinkingLevel>(WORKFLOW_THINKING_LEVELS);
+const HOST_FALLBACK_THINKING: Record<WorkflowModelProfileName, ThinkingLevel> = {
+  small: "low",
+  medium: "medium",
+  big: "high",
+};
+const CONFIG_FILE_NAME = "workflow-models.json";
+
+export function workflowModelProfilePaths(
+  cwd: string,
+  agentDir: string = getAgentDir(),
+): WorkflowModelProfilePaths {
+  return {
+    user: join(agentDir, CONFIG_FILE_NAME),
+    project: join(cwd, ".pi", CONFIG_FILE_NAME),
+  };
+}
+
+export function resolveWorkflowModelProfiles(input: {
+  readonly cwd: string;
+  readonly modelRegistry: Pick<ModelRegistry, "find">;
+  readonly hostModel: Model<Api> | undefined;
+  readonly paths?: WorkflowModelProfilePaths;
+}): ResolvedWorkflowModelProfiles {
+  const paths = input.paths ?? workflowModelProfilePaths(input.cwd);
+  const user = readWorkflowModelProfileFile(paths.user);
+  const project = readWorkflowModelProfileFile(paths.project);
+  const resolved = { ...hostWorkflowModelProfiles(input.hostModel) };
+
+  for (const name of WORKFLOW_MODEL_PROFILE_NAMES) {
+    const projectProfile = project.profiles[name];
+    const configured = projectProfile ?? user.profiles[name];
+    if (!configured) continue;
+
+    const source = projectProfile ? "project" : "user";
+    const configPath = paths[source];
+    resolved[name] = {
+      name,
+      model: resolveConfiguredModel(name, configured.model, input.modelRegistry, configPath),
+      thinkingLevel: configured.thinkingLevel,
+      source,
+      configPath,
+    };
+  }
+
+  return resolved;
+}
+
+export function hostWorkflowModelProfiles(
+  hostModel: Model<Api> | undefined,
+): ResolvedWorkflowModelProfiles {
+  return {
+    small: { name: "small", model: hostModel, thinkingLevel: HOST_FALLBACK_THINKING.small, source: "host" },
+    medium: { name: "medium", model: hostModel, thinkingLevel: HOST_FALLBACK_THINKING.medium, source: "host" },
+    big: { name: "big", model: hostModel, thinkingLevel: HOST_FALLBACK_THINKING.big, source: "host" },
+  };
+}
+
+export function resolveAgentModelProfile(
+  input: {
+    readonly request: WorkflowModelRouteRequest;
+    readonly profiles: ResolvedWorkflowModelProfiles;
+    readonly resolveExplicitModel: (modelRef: string) => Model<Api> | undefined;
+    readonly hostModel: Model<Api> | undefined;
+  },
+): { readonly model: Model<Api> | undefined; readonly thinkingLevel: ThinkingLevel | undefined } {
+  const profile = input.request.profile === undefined
+    ? undefined
+    : input.profiles[assertWorkflowModelProfileName(input.request.profile)];
+  return {
+    model: input.request.model === undefined
+      ? (profile?.model ?? input.hostModel)
+      : input.resolveExplicitModel(input.request.model),
+    thinkingLevel: input.request.thinkingLevel ?? profile?.thinkingLevel,
+  };
+}
+
+export function readWorkflowModelProfileFile(configPath: string): WorkflowModelProfileFile {
+  let contents: string;
+  try {
+    contents = readFileSync(configPath, "utf8");
+  } catch (error) {
+    if (isMissingPathError(error)) return { profiles: {} };
+    throw new WorkflowModelProfileConfigError(
+      `Could not read workflow model profiles at ${configPath}: ${unknownErrorMessage(error)}. Fix the file permissions or remove the file.`,
+      configPath,
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(contents);
+  } catch (error) {
+    throw new WorkflowModelProfileConfigError(
+      `Invalid JSON in workflow model profiles at ${configPath}: ${unknownErrorMessage(error)}. Fix or remove the file.`,
+      configPath,
+    );
+  }
+  return parseWorkflowModelProfileFile(parsed, configPath);
+}
+
+export function setWorkflowModelProfile(input: {
+  readonly configPath: string;
+  readonly name: WorkflowModelProfileName;
+  readonly profile: WorkflowModelProfileConfig;
+  readonly modelRegistry: Pick<ModelRegistry, "find">;
+}): void {
+  const current = readWorkflowModelProfileFile(input.configPath);
+  const next = { ...current.profiles, [input.name]: input.profile };
+  for (const name of WORKFLOW_MODEL_PROFILE_NAMES) {
+    const profile = next[name];
+    if (profile) resolveConfiguredModel(name, profile.model, input.modelRegistry, input.configPath);
+  }
+  writeWorkflowModelProfileFile(input.configPath, { profiles: next });
+}
+
+export function clearWorkflowModelProfile(configPath: string, name: WorkflowModelProfileName): void {
+  const current = readWorkflowModelProfileFile(configPath);
+  if (!current.profiles[name]) return;
+  const profiles = { ...current.profiles };
+  delete profiles[name];
+  writeWorkflowModelProfileFile(configPath, { profiles });
+}
+
+export function isWorkflowModelProfileName(value: string): value is WorkflowModelProfileName {
+  return WORKFLOW_MODEL_PROFILE_NAMES.includes(value as WorkflowModelProfileName);
+}
+
+export function isWorkflowThinkingLevel(value: string): value is ThinkingLevel {
+  return THINKING_LEVELS.has(value as ThinkingLevel);
+}
+
+function parseWorkflowModelProfileFile(value: unknown, configPath: string): WorkflowModelProfileFile {
+  if (!isRecord(value)) throw invalidConfig(configPath, "the root must be an object");
+  assertOnlyKeys(value, ["profiles"], configPath);
+  if (!isRecord(value.profiles)) throw invalidConfig(configPath, '"profiles" must be an object');
+
+  const profiles: Partial<Record<WorkflowModelProfileName, WorkflowModelProfileConfig>> = {};
+  for (const [name, profile] of Object.entries(value.profiles)) {
+    if (!isWorkflowModelProfileName(name)) {
+      throw invalidConfig(configPath, `unknown profile "${name}"; expected small, medium, or big`);
+    }
+    if (!isRecord(profile)) throw invalidConfig(configPath, `profile "${name}" must be an object`, name);
+    assertOnlyKeys(profile, ["model", "thinkingLevel"], configPath, name);
+    if (typeof profile.model !== "string") {
+      throw invalidConfig(configPath, `profile "${name}" requires a provider-qualified "model" string`, name);
+    }
+    assertThinkingLevel(profile.thinkingLevel, configPath, name);
+    profiles[name] = {
+      model: profile.model,
+      ...(profile.thinkingLevel === undefined ? {} : { thinkingLevel: profile.thinkingLevel }),
+    };
+  }
+  return { profiles };
+}
+
+function resolveConfiguredModel(
+  name: WorkflowModelProfileName,
+  modelRef: string,
+  modelRegistry: Pick<ModelRegistry, "find">,
+  configPath: string,
+): Model<Api> {
+  const slash = modelRef.indexOf("/");
+  if (modelRef.trim() !== modelRef || slash <= 0 || slash === modelRef.length - 1) {
+    throw invalidConfig(
+      configPath,
+      `profile "${name}" model must be an exact provider/model identity; received "${modelRef}"`,
+      name,
+    );
+  }
+  const provider = modelRef.slice(0, slash);
+  const modelId = modelRef.slice(slash + 1);
+  if (/\s/.test(provider) || modelId.startsWith("/") || modelId.endsWith("/") || /\s/.test(modelId)) {
+    throw invalidConfig(
+      configPath,
+      `profile "${name}" model must be an exact provider/model identity; received "${modelRef}"`,
+      name,
+    );
+  }
+  const model = modelRegistry.find(provider, modelId);
+  if (!model) {
+    throw invalidConfig(
+      configPath,
+      `profile "${name}" references unavailable model "${modelRef}"; update ${configPath} with an exact provider/model identity`,
+      name,
+    );
+  }
+  return model;
+}
+
+function assertWorkflowModelProfileName(value: string): WorkflowModelProfileName {
+  if (isWorkflowModelProfileName(value)) return value;
+  throw new Error(`Unknown workflow model profile "${value}"; expected small, medium, or big.`);
+}
+
+function assertThinkingLevel(
+  value: unknown,
+  configPath: string,
+  profile: WorkflowModelProfileName,
+): asserts value is ThinkingLevel | undefined {
+  if (value === undefined || (typeof value === "string" && isWorkflowThinkingLevel(value))) return;
+  throw invalidConfig(
+    configPath,
+    `profile "${profile}" thinkingLevel must be off, minimal, low, medium, high, xhigh, or max`,
+    profile,
+  );
+}
+
+function assertOnlyKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+  configPath: string,
+  profile?: WorkflowModelProfileName,
+): void {
+  const unexpected = Object.keys(value).find((key) => !allowed.includes(key));
+  if (unexpected) throw invalidConfig(configPath, `unexpected key "${unexpected}"`, profile);
+}
+
+function writeWorkflowModelProfileFile(configPath: string, config: WorkflowModelProfileFile): void {
+  const temporaryPath = `${configPath}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync(temporaryPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+    renameSync(temporaryPath, configPath);
+  } catch (error) {
+    try {
+      unlinkSync(temporaryPath);
+    } catch {
+      // Best effort: preserve the original write error.
+    }
+    throw new WorkflowModelProfileConfigError(
+      `Could not write workflow model profiles at ${configPath}: ${unknownErrorMessage(error)}.`,
+      configPath,
+    );
+  }
+}
+
+function invalidConfig(
+  configPath: string,
+  reason: string,
+  profile?: WorkflowModelProfileName,
+): WorkflowModelProfileConfigError {
+  return new WorkflowModelProfileConfigError(
+    `Invalid workflow model profile config at ${configPath}: ${reason}.`,
+    configPath,
+    profile,
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}