@really-knows-ai/foundry 2.3.2 → 3.0.0

package/dist/.opencode/plugins/foundry-tools/helpers.js

@@ -0,0 +1,340 @@
+// Shared helpers for the Foundry plugin. Pure functions — no plugin deps.
+
+import path from 'path';
+import { readFileSync, writeFileSync, existsSync, readdirSync, unlinkSync, mkdirSync, renameSync, rmSync, statSync } from 'fs';
+import { execFileSync } from 'child_process';
+import { getCycleDefinition } from '../../../scripts/lib/config.js';
+import { getOrOpenStore, getContext } from '../../../scripts/lib/memory/singleton.js';
+import { resolvePermissions } from '../../../scripts/lib/memory/permissions.js';
+import { renderMemoryPrompt } from '../../../scripts/lib/memory/prompt.js';
+import { loadExtractor } from '../../../scripts/lib/assay/loader.js';
+import { requireOnFlowBranch } from '../../../scripts/lib/branch-guard.js';
+
+// Track flow files we've already warned about to avoid spamming stderr
+const warnedFlowFiles = new Set();
+
+// -- Frontmatter parsing helpers --
+
+function isFieldSeparator(char) {
+  return char === ' ' || char === '\t';
+}
+
+function parseFrontmatterField(fm, fieldName) {
+  const prefix = `${fieldName}:`;
+  for (const line of fm.split('\n')) {
+    if (!line.startsWith(prefix)) continue;
+    const rest = line.slice(prefix.length);
+    if (rest === '' || isFieldSeparator(rest[0])) {
+      return rest.trim();
+    }
+  }
+  return null;
+}
+
+function parseStartingCycles(fm) {
+  const lines = fm.split('\n');
+  const scIndex = lines.findIndex(line => line.trimEnd() === 'starting-cycles:');
+  if (scIndex < 0) return [];
+  const items = [];
+  for (let i = scIndex + 1; i < lines.length; i++) {
+    const trimmed = lines[i].trimStart();
+    if (trimmed.startsWith('-')) {
+      const content = trimmed.slice(1).trimStart();
+      if (content) items.push(content);
+    } else {
+      break;
+    }
+  }
+  return items;
+}
+
+function parseFlowFrontmatter(text, entry) {
+  const fmMatch = text.match(/^---\n([\s\S]*?)\n---/);
+  if (!fmMatch) return null;
+  const fm = fmMatch[1];
+  const id = parseFrontmatterField(fm, 'id') || entry.replace(/\.md$/, '');
+  const name = parseFrontmatterField(fm, 'name') || id;
+  const startingCycles = parseStartingCycles(fm);
+  return { id, name, startingCycles };
+}
+
+function parseFlowFile(entry, flowsDir) {
+  try {
+    const text = readFileSync(path.join(flowsDir, entry), 'utf-8');
+    return parseFlowFrontmatter(text, entry);
+  } catch (err) {
+    if (!warnedFlowFiles.has(entry)) {
+      console.warn(`Warning: Skipping malformed flow file ${entry}: ${err.message}`);
+      warnedFlowFiles.add(entry);
+    }
+    const id = entry.replace(/\.md$/, '');
+    return { id, name: id, startingCycles: [], error: err.message };
+  }
+}
+
+function isFlowFile(entry) {
+  return entry.endsWith('.md') && entry !== '.gitkeep';
+}
+
+export function listFlows(foundryDir) {
+  const flowsDir = path.join(foundryDir, 'flows');
+  if (!existsSync(flowsDir)) return [];
+  const flows = [];
+  for (const entry of readdirSync(flowsDir)) {
+    if (!isFlowFile(entry)) continue;
+    const parsed = parseFlowFile(entry, flowsDir);
+    if (parsed) flows.push(parsed);
+  }
+  return flows;
+}
+
+// -- Bootstrap content helpers --
+
+function buildFoundryNotInitializedMessage() {
+  return `<FOUNDRY_CONTEXT>
+Foundry is installed but not initialised in this project. There is no foundry/ directory.
+
+To set up Foundry, use the \`init-foundry\` skill. This will create the foundry/ directory structure
+and guide you through defining artefact types, laws, appraisers, cycles, and flows.
+</FOUNDRY_CONTEXT>`;
+}
+
+function buildFlowList(flows) {
+  if (flows.length === 0) {
+    return '- (no flows defined yet — use the `add-flow` skill to create one)';
+  }
+  return flows.map(f => {
+    const sc = f.startingCycles.length > 0 ? ` — starting cycles: ${f.startingCycles.join(', ')}` : '';
+    return `- \`${f.id}\` — ${f.name}${sc}`;
+  }).join('\n');
+}
+
+function buildFoundryInitializedMessage(flowList, packageRoot) {
+  return `<FOUNDRY_CONTEXT>
+Foundry is active in this project. The foundry/ directory contains the project's artefact definitions,
+laws, appraisers, cycles, and flows.
+
+Foundry is a skill-driven framework for governed artefact generation and evaluation.
+The pipeline: assay (populate memory) → forge (produce) → quench (deterministic checks) → appraise (subjective evaluation) → human-appraise (human review) → iterate.
+
+## Defined flows
+
+${flowList}
+
+**CRITICAL ROUTING RULE:** When the user references any flow above — by id (e.g. "creative-flow"),
+by name (e.g. "Creative Flow"), or by clear paraphrase (e.g. "the creative flow", "use the creative pipeline") —
+invoke the \`flow\` skill DIRECTLY with that flow's id. Do NOT invoke brainstorming, do NOT explore the
+codebase, do NOT ask clarifying questions about what to build. The flow's cycles already define the
+work. The user's request text (e.g. "make a haiku about X") is the goal to pass to the flow.
+
+Brainstorming applies to NEW features being added to foundry itself (new cycles, new artefact types,
+new skills). It does NOT apply to running an existing, defined flow.
+
+## Available skills
+
+- **Pipeline:** assay, forge, quench, appraise, orchestrate, flow, human-appraise
+- **Authoring:** add-artefact-type, add-law, add-appraiser, add-cycle, add-flow, add-memory-entity-type, add-memory-edge-type, add-extractor, init-foundry
+- **Maintenance:** upgrade-foundry, refresh-agents, list-agents, init-memory, change-embedding-model, dry-run
+- **Memory Admin:** drop-memory-entity-type, drop-memory-edge-type, rename-memory-entity-type, rename-memory-edge-type, reset-memory
+
+## Multi-model routing
+
+Foundry uses \`foundry-*\` sub-agents defined as markdown files in \`.opencode/agents/\`.
+Run the \`refresh-agents\` skill to regenerate them after adding or removing providers.
+Cycle definitions can specify per-stage models via the \`models\` frontmatter map. Appraisers can override with their own \`model\` field.
+
+All user content lives under foundry/.
+Scripts are located at: ${path.join(packageRoot, 'scripts')}
+</FOUNDRY_CONTEXT>`;
+}
+
+export function getBootstrapContent(directory, packageRoot) {
+  const foundryDir = path.join(directory, 'foundry');
+  const foundryExists = existsSync(foundryDir) && statSync(foundryDir).isDirectory();
+
+  if (!foundryExists) {
+    return buildFoundryNotInitializedMessage();
+  }
+
+  const flows = listFlows(foundryDir);
+  const flowList = buildFlowList(flows);
+  return buildFoundryInitializedMessage(flowList, packageRoot);
+}
+
+/**
+ * Factory for creating exec functions used across plugin tools.
+ * Returns a function that executes commands via execFileSync.
+ * Used by tools that need to run git or other CLI commands.
+ */
+export function makeExec(cwd) {
+  return (argv) => execFileSync(argv[0], argv.slice(1), {
+    cwd, encoding: 'utf8', stdio: 'pipe',
+  });
+}
+
+/**
+ * Guard function that ensures a tool is called on a flow branch (work/* or dry-run/*).
+ * Used by guarded() to enforce branch requirements for flow-tier mutations.
+ * Returns the result of requireOnFlowBranch({ exec }).
+ */
+export function flowBranchGuard(_args, context) {
+  return requireOnFlowBranch({ exec: makeExec(context.worktree) });
+}
+
+export function makeIO(directory) {
+  const resolve = (p) => path.isAbsolute(p) ? p : path.join(directory, p);
+  return {
+    exists: (p) => existsSync(resolve(p)),
+    readFile: (p) => readFileSync(resolve(p), 'utf-8'),
+    writeFile: (p, content) => writeFileSync(resolve(p), content, 'utf-8'),
+    readDir: (p) => readdirSync(resolve(p)),
+    mkdir: (p) => mkdirSync(resolve(p), { recursive: true }),
+    // unlink: succeeds silently when the file is missing.
+    unlink: (p) => { if (existsSync(resolve(p))) unlinkSync(resolve(p)); },
+    rename: (from, to) => renameSync(resolve(from), resolve(to)),
+    // exec: run a command in the worktree and return stdout as a UTF-8 string.
+    // Used by sort.js (getDirtyToolManagedFiles, getModifiedFiles) for git enforcement.
+    // Takes an array [command, ...args] to prevent shell injection.
+    // Throws on non-zero exit; callers already wrap in try/catch.
+    exec: (argv) => execFileSync(argv[0], argv.slice(1), { cwd: directory, encoding: 'utf8', stdio: 'pipe' }),
+  };
+}
+
+/**
+ * Factory used by guarded() to resolve the current branch.
+ * Returns an object exposing `exec(argv: string[]) => string` (stdout).
+ */
+export function branchIoFactory(context) {
+  const cwd = context.worktree;
+  return {
+    exec: (argv) => execFileSync(argv[0], argv.slice(1),
+      { cwd, encoding: 'utf8', stdio: 'pipe' }),
+  };
+}
+
+/**
+ * Factory used by guarded() for tracing IO. Returns the existing
+ * async IO shape (mkdirp/exists/readFile/writeFile) plus an
+ * `appendFile` for trace appends.
+ */
+export function asyncIoFactory(context) {
+  const sync = makeIO(context.worktree);
+  return {
+    exists: async (p) => sync.exists(p),
+    readFile: async (p) => sync.readFile(p),
+    writeFile: async (p, c) => sync.writeFile(p, c),
+    mkdirp: async (p) => sync.mkdir(p),
+    appendFile: async (p, c) => {
+      const existing = sync.exists(p) ? sync.readFile(p) : '';
+      sync.writeFile(p, existing + c);
+    },
+  };
+}
+
+export function makeMemoryIO(directory) {
+  // Memory modules use await on every I/O op. Wrap sync fs calls in Promise-returning shims.
+  const sync = makeIO(directory);
+  return {
+    exists: async (p) => sync.exists(p),
+    readFile: async (p) => sync.readFile(p),
+    writeFile: async (p, c) => sync.writeFile(p, c),
+    readDir: async (p) => { try { return sync.readDir(p); } catch { return []; } },
+    mkdir: async (p) => sync.mkdir(p),
+    unlink: async (p) => sync.unlink(p),
+    rename: async (from, to) => sync.rename(from, to),
+  };
+}
+
+export function errorJson(err) {
+  return JSON.stringify({ error: err.message ?? String(err) });
+}
+
+/**
+ * Async IO contract consumed by the config-creators layer.
+ *
+ * The creators take an io with `exists, readFile, writeFile, mkdirp,
+ * readDir`. We reuse `makeIO`'s sync fs calls and wrap them in
+ * Promise-returning shims; `makeIO.mkdir` already passes
+ * `{ recursive: true }`, so it satisfies `mkdirp` semantics.
+ */
+export function makeAsyncIO(directory) {
+  const sync = makeIO(directory);
+  const resolve = (p) => path.isAbsolute(p) ? p : path.join(directory, p);
+  return {
+    exists: async (p) => sync.exists(p),
+    readFile: async (p) => sync.readFile(p),
+    writeFile: async (p, c) => sync.writeFile(p, c),
+    mkdirp: async (p) => sync.mkdir(p),
+    readDir: async (p) => { try { return sync.readDir(p); } catch { return []; } },
+    // `readdir` (lowercase) alias matching the snapshot inspect.js contract.
+    readdir: async (p) => { try { return sync.readDir(p); } catch { return []; } },
+    rm: async (p, opts = {}) => {
+      const full = resolve(p);
+      if (existsSync(full)) {
+        rmSync(full, { recursive: !!opts.recursive, force: true });
+      }
+    },
+  };
+}
+
+// -- buildCyclePromptExtras helpers --
+
+function getExtractorNames(cycleDef) {
+  const assayBlock = cycleDef?.frontmatter?.assay;
+  return Array.isArray(assayBlock?.extractors) ? assayBlock.extractors : [];
+}
+
+function shouldLoadExtractors(cycleDef, stage) {
+  const stageBase = typeof stage === 'string' ? stage.split(':')[0] : '';
+  return stageBase === 'forge' && getExtractorNames(cycleDef).length > 0;
+}
+
+async function loadExtractors(worktree, cycleDef, io) {
+  const extractorNames = getExtractorNames(cycleDef);
+  const foundryDir = path.join(worktree, 'foundry');
+  const extractors = [];
+  for (const name of extractorNames) {
+    try {
+      const ex = await loadExtractor(foundryDir, name, io);
+      extractors.push({ name: ex.name, body: ex.body });
+    } catch (err) {
+      if (process.env.FOUNDRY_DIAGNOSTICS === '1') {
+        console.error(`buildCyclePromptExtras: Failed to load extractor '${name}': ${err.message}`);
+      }
+    }
+  }
+  return extractors.length > 0 ? extractors : undefined;
+}
+
+async function buildCyclePromptInternal({ worktree, cycleId, stage }) {
+  const io = makeMemoryIO(worktree);
+  const store = await getOrOpenStore({ worktreeRoot: worktree, io });
+  const ctx = getContext(worktree);
+  if (!ctx) return '';
+  const cycleDef = await getCycleDefinition('foundry', cycleId, io);
+  const perms = resolvePermissions({ cycleFrontmatter: cycleDef.frontmatter, vocabulary: ctx.vocabulary });
+
+  let extractors;
+  if (shouldLoadExtractors(cycleDef, stage)) {
+    extractors = await loadExtractors(worktree, cycleDef, io);
+  }
+
+  return renderMemoryPrompt({ permissions: perms, schema: store?.schema, extractors });
+}
+
+/**
+ * Build the memory-vocabulary block for a cycle's dispatch prompt.
+ * Returns '' on any error (memory not initialised, drifted, etc.) so that
+ * flow dispatch never fails due to memory.
+ */
+export async function buildCyclePromptExtras({ worktree, cycleId, stage }) {
+  if (!cycleId) return '';
+  try {
+    return await buildCyclePromptInternal({ worktree, cycleId, stage });
+  } catch (err) {
+    if (process.env.FOUNDRY_DIAGNOSTICS === '1') {
+      console.error(`buildCyclePromptExtras: Memory context failed for cycle '${cycleId}': ${err.message}`);
+    }
+    return '';
+  }
+}

package/dist/.opencode/plugins/foundry-tools/history-tools.js

@@ -0,0 +1,20 @@
+import path from 'path';
+import { loadHistory } from '../../../scripts/lib/history.js';
+import { makeIO } from './helpers.js';
+
+export function createHistoryTools({ tool }) {
+  return {
+    foundry_history_list: tool({
+      description: 'List history entries for a cycle',
+      args: {
+        cycle: tool.schema.string().describe('Cycle name'),
+      },
+      async execute(args, context) {
+        const io = makeIO(context.worktree);
+        const historyPath = path.join(context.worktree, 'WORK.history.yaml');
+        const entries = loadHistory(historyPath, args.cycle, io);
+        return JSON.stringify(entries);
+      },
+    }),
+  };
+}

package/dist/.opencode/plugins/foundry-tools/memory-admin-tools.js

@@ -0,0 +1,296 @@
+import path from 'path';
+import { existsSync, unlinkSync, renameSync } from 'fs';
+import { createEntityType as admCreateEntity } from '../../../scripts/lib/memory/admin/create-entity-type.js';
+import { createExtractor as admCreateExtractor } from '../../../scripts/lib/memory/admin/create-extractor.js';
+import { createEdgeType as admCreateEdge } from '../../../scripts/lib/memory/admin/create-edge-type.js';
+import { renameEntityType as admRenameEntity } from '../../../scripts/lib/memory/admin/rename-entity-type.js';
+import { renameEdgeType as admRenameEdge } from '../../../scripts/lib/memory/admin/rename-edge-type.js';
+import { dropEntityType as admDropEntity } from '../../../scripts/lib/memory/admin/drop-entity-type.js';
+import { dropEdgeType as admDropEdge } from '../../../scripts/lib/memory/admin/drop-edge-type.js';
+import { resetMemory as admReset } from '../../../scripts/lib/memory/admin/reset.js';
+import { validateMemory as admValidate } from '../../../scripts/lib/memory/admin/validate.js';
+import { dumpMemory as admDump } from '../../../scripts/lib/memory/admin/dump.js';
+import { vacuumMemory as admVacuum } from '../../../scripts/lib/memory/admin/vacuum.js';
+import { reembed as admReembed } from '../../../scripts/lib/memory/admin/reembed.js';
+import { initMemory as admInitMemory } from '../../../scripts/lib/memory/admin/init.js';
+import { loadMemoryConfig, writeMemoryConfig } from '../../../scripts/lib/memory/config.js';
+import { embed as memEmbed, probeEmbeddings as memProbeEmbeddings } from '../../../scripts/lib/memory/embeddings.js';
+import { withStore } from './memory-helpers.js';
+import { makeMemoryIO, makeIO, makeExec, errorJson, branchIoFactory, asyncIoFactory } from './helpers.js';
+import { requireNotFailed } from '../../../scripts/lib/failed-flow.js';
+import { requireOnConfigBranch } from '../../../scripts/lib/branch-guard.js';
+import { guarded } from '../../../scripts/lib/guards.js';
+
+// Failed-flow guard policy for memory admin tools.
+//
+// Rule: any tool that mutates state (disk or live DB) is blocked when
+// WORK.md has `status: failed`, because the work-branch FS is the
+// source-of-truth that gets thrown away on abandon-and-retry, and any
+// further mutations would be lost or compound the drift.
+//
+// Read-only diagnostics (`dump`, `validate`) are intentionally exempt —
+// the human/LLM needs them to figure out what went wrong before
+// abandoning the cycle.
+//
+// requireNotFailed expects a sync IO (it parses WORK.md synchronously),
+// so we use makeIO here in place of the async makeMemoryIO that the
+// admin tool bodies themselves consume.
+function notFailedGuard(_args, context) {
+  return requireNotFailed(makeIO(context.worktree));
+}
+
+// Schema-mutating admin tools must run on a config/<description> branch
+// so the resulting commits land on a branch that finishes via
+// `foundry_git_finish` (config kind) and stay isolated from main and any
+// in-progress flow work branch.
+//
+// Read-only tools (validate, dump) and the meta tool (vacuum) are exempt
+// — vacuum touches no tracked files and the read-only tools are needed
+// for diagnosis from any branch.
+function configBranchGuard(_args, context) {
+  return requireOnConfigBranch({ exec: makeExec(context.worktree) });
+}
+
+// ── Execute handler factories ──────────────────────────────────────────
+
+function adminExecute(adminFn) {
+  return guarded(adminFn.name, [configBranchGuard, notFailedGuard], async (args, context) => {
+    try {
+      const io = makeMemoryIO(context.worktree);
+      const out = await adminFn({ worktreeRoot: context.worktree, io, ...args });
+      return JSON.stringify(out);
+    } catch (err) { return errorJson(err); }
+  }, { branchIo: branchIoFactory, io: asyncIoFactory });
+}
+
+// ── Individual tool factories ──────────────────────────────────────────
+
+function toolCreateEntityType({ tool }) {
+  return tool({
+    description: 'Create a new entity type with a prose body brief.',
+    args: {
+      name: tool.schema.string(),
+      body: tool.schema.string(),
+    },
+    execute: adminExecute(admCreateEntity),
+  });
+}
+
+function toolExtractorCreate({ tool }) {
+  return tool({
+    description: 'Create a new extractor definition under foundry/memory/extractors/.',
+    args: {
+      name: tool.schema.string(),
+      command: tool.schema.string(),
+      memoryWrite: tool.schema.array(tool.schema.string()),
+      body: tool.schema.string(),
+      timeout: tool.schema.string().optional(),
+    },
+    execute: adminExecute(admCreateExtractor),
+  });
+}
+
+function toolCreateEdgeType({ tool }) {
+  return tool({
+    description: 'Create a new edge type.',
+    args: {
+      name: tool.schema.string(),
+      sources: tool.schema.union([tool.schema.literal('any'), tool.schema.array(tool.schema.string())]),
+      targets: tool.schema.union([tool.schema.literal('any'), tool.schema.array(tool.schema.string())]),
+      body: tool.schema.string(),
+    },
+    execute: adminExecute(admCreateEdge),
+  });
+}
+
+function toolRenameEntityType({ tool }) {
+  return tool({
+    description: 'Rename an entity type and cascade updates to edges and rows.',
+    args: { from: tool.schema.string(), to: tool.schema.string() },
+    execute: adminExecute(admRenameEntity),
+  });
+}
+
+function toolRenameEdgeType({ tool }) {
+  return tool({
+    description: 'Rename an edge type.',
+    args: { from: tool.schema.string(), to: tool.schema.string() },
+    execute: adminExecute(admRenameEdge),
+  });
+}
+
+function toolDropEntityType({ tool }) {
+  return tool({
+    description:
+      'Destructive. Delete an entity type and cascade to affected edges. Call without confirm (or confirm:false) to get a preview of what would be deleted. Pass confirm:true to actually drop.',
+    args: { name: tool.schema.string(), confirm: tool.schema.boolean().optional() },
+    execute: adminExecute(admDropEntity),
+  });
+}
+
+function toolDropEdgeType({ tool }) {
+  return tool({
+    description:
+      'Destructive. Delete an edge type. Call without confirm (or confirm:false) to preview row count. Pass confirm:true to actually drop.',
+    args: { name: tool.schema.string(), confirm: tool.schema.boolean().optional() },
+    execute: adminExecute(admDropEdge),
+  });
+}
+
+function toolReset({ tool }) {
+  return tool({
+    description: 'Destructive. Purge all memory data (keeps type definitions). Requires confirm: true.',
+    args: { confirm: tool.schema.boolean() },
+    execute: adminExecute(admReset),
+  });
+}
+
+function toolValidate({ tool }) {
+  return tool({
+    description: 'Run load-time and drift checks; returns a report.',
+    args: {},
+    async execute(_args, context) {
+      try {
+        const io = makeMemoryIO(context.worktree);
+        return JSON.stringify(await admValidate({ io }));
+      } catch (err) { return errorJson(err); }
+    },
+  });
+}
+
+function toolInit({ tool }) {
+  return tool({
+    description:
+      'Scaffold foundry/memory/: creates entities/edges/relations dirs with .gitkeep, writes config.md and schema.json, appends .gitignore entries, and optionally probes the embedding provider. Fails if foundry/memory/ already exists.',
+    args: {
+      embeddings_enabled: tool.schema.boolean().optional(),
+      probe: tool.schema.boolean().optional(),
+    },
+    execute: guarded('foundry_memory_init', [configBranchGuard, notFailedGuard], async (args, context) => {
+      try {
+        const io = makeMemoryIO(context.worktree);
+        const out = await admInitMemory({
+          io,
+          embeddingsEnabled: args.embeddings_enabled ?? true,
+          probe: args.probe ?? true,
+        });
+        return JSON.stringify(out);
+      } catch (err) { return errorJson(err); }
+    }, { branchIo: branchIoFactory, io: asyncIoFactory }),
+  });
+}
+
+function toolDump({ tool }) {
+  return tool({
+    description: 'Human-readable snapshot of memory. Optional type + name.',
+    args: {
+      type: tool.schema.string().optional(),
+      name: tool.schema.string().optional(),
+      depth: tool.schema.number().optional(),
+    },
+    async execute(args, context) {
+      try {
+        const { store, vocabulary } = await withStore(context);
+        const dump = await admDump({ store, vocabulary, ...args });
+        return JSON.stringify({ dump });
+      } catch (err) { return errorJson(err); }
+    },
+  });
+}
+
+function toolVacuum({ tool }) {
+  return tool({
+    description: 'Compact the Cozo database.',
+    args: {},
+    execute: guarded('foundry_memory_vacuum', [notFailedGuard], async (_args, context) => {
+      try {
+        const { store } = await withStore(context);
+        return JSON.stringify(await admVacuum({ store }));
+      } catch (err) { return errorJson(err); }
+    }, { branchIo: branchIoFactory, io: asyncIoFactory }),
+  });
+}
+
+// ── change_embedding_model helpers ─────────────────────────────────────
+
+function buildNewEmbeddingConfig(baseConfig, args) {
+  return {
+    ...baseConfig,
+    enabled: true,
+    model: args.model,
+    dimensions: args.dimensions,
+    baseURL: args.baseURL ?? baseConfig.baseURL,
+    apiKey: args.apiKey ?? baseConfig.apiKey,
+  };
+}
+
+function validateEmbeddingProbe(probe, args) {
+  if (!probe.ok) return new Error(`probe failed: ${probe.error}`);
+  if (probe.dimensions !== args.dimensions) {
+    return new Error(`provider returned ${probe.dimensions}-dim vectors, config declares ${args.dimensions}`);
+  }
+  return null;
+}
+
+function makeRawIO() {
+  return {
+    exists: (p) => existsSync(p),
+    unlink: (p) => { if (existsSync(p)) unlinkSync(p); },
+    rename: (from, to) => renameSync(from, to),
+  };
+}
+
+function toolChangeEmbeddingModel({ tool }) {
+  return tool({
+    description: 'Swap the embedding model and re-embed all existing entities.',
+    args: {
+      model: tool.schema.string(),
+      dimensions: tool.schema.number(),
+      baseURL: tool.schema.string().optional(),
+      apiKey: tool.schema.string().optional(),
+    },
+    execute: guarded('foundry_memory_change_embedding_model', [configBranchGuard, notFailedGuard], async (args, context) => {
+      try {
+        const io = makeMemoryIO(context.worktree);
+        const currentConfig = await loadMemoryConfig('foundry', io);
+        const newConfig = buildNewEmbeddingConfig(currentConfig.embeddings, args);
+        const probe = await memProbeEmbeddings({ config: newConfig });
+        const probeError = validateEmbeddingProbe(probe, args);
+        if (probeError) return errorJson(probeError);
+        const dbAbsolutePath = path.join(context.worktree, 'foundry/memory/memory.db');
+        const embedder = (inputs) => memEmbed({ config: newConfig, inputs });
+        const out = await admReembed({
+          worktreeRoot: context.worktree,
+          io,
+          rawIO: makeRawIO(),
+          dbAbsolutePath,
+          newModel: args.model,
+          newDimensions: args.dimensions,
+          embedder,
+        });
+        await writeMemoryConfig('foundry', { embeddings: newConfig }, io);
+        return JSON.stringify(out);
+      } catch (err) { return errorJson(err); }
+    }, { branchIo: branchIoFactory, io: asyncIoFactory }),
+  });
+}
+
+// ── Export ─────────────────────────────────────────────────────────────
+
+export function createMemoryAdminTools({ tool }) {
+  return {
+    foundry_memory_create_entity_type: toolCreateEntityType({ tool }),
+    foundry_extractor_create: toolExtractorCreate({ tool }),
+    foundry_memory_create_edge_type: toolCreateEdgeType({ tool }),
+    foundry_memory_rename_entity_type: toolRenameEntityType({ tool }),
+    foundry_memory_rename_edge_type: toolRenameEdgeType({ tool }),
+    foundry_memory_drop_entity_type: toolDropEntityType({ tool }),
+    foundry_memory_drop_edge_type: toolDropEdgeType({ tool }),
+    foundry_memory_reset: toolReset({ tool }),
+    foundry_memory_validate: toolValidate({ tool }),
+    foundry_memory_init: toolInit({ tool }),
+    foundry_memory_dump: toolDump({ tool }),
+    foundry_memory_vacuum: toolVacuum({ tool }),
+    foundry_memory_change_embedding_model: toolChangeEmbeddingModel({ tool }),
+  };
+}