@agentprojectcontext/apx 1.57.0 → 1.59.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.57.0",
+  "version": "1.59.0",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"

package/src/core/agent/skills/index.js

@@ -3,6 +3,15 @@ export { condenseSkillDescription, buildSkillsHintBlock } from "./catalog.js";
 export { tryResolveSkillCommand } from "./trigger.js";
 export { suggestSkillForPrompt, clearSkillVectorCache } from "./rag.js";
 export { listSkills, loadSkill, SKILL_LOCATIONS } from "./loader.js";
+export {
+  isPrivateSkill,
+  isSkillEnabled,
+  filterEnabledSkills,
+  annotateSkills,
+  setSkillEnabled,
+  resolveScopeKey,
+  DEFAULT_SCOPE,
+} from "./policy.js";
 export {
   inspectPromptForSkills,
   isInspectorEnabled,

package/src/core/agent/skills/inspector.js

@@ -25,6 +25,7 @@
 
 import { embedOne, cosineSim } from "#core/memory/embeddings.js";
 import { listSkills, loadSkill } from "./loader.js";
+import { filterEnabledSkills, isSkillEnabled } from "./policy.js";
 import { readIndex, backgroundRefreshIfStale } from "./index-store.js";
 
 // Defaults — exported so the CLI/web can render them.
@@ -187,7 +188,8 @@ export async function inspectPromptForSkills({ prompt, projectPath, globalConfig
     };
   }
 
-  const scored = scoreAgainstIndex(probe.vector, items);
+  const scored = scoreAgainstIndex(probe.vector, items).filter((s) =>
+    isSkillEnabled(s, { config: globalConfig, projectPath }));
   return await pickAndRender({ scored, projectPath, probe, cfg });
 }
 
@@ -196,7 +198,10 @@ export async function inspectPromptForSkills({ prompt, projectPath, globalConfig
 // ---------------------------------------------------------------------------
 
 async function inspectFromLive({ text, projectPath, cfg, globalConfig, embedOpts }) {
-  const skills = listSkills({ projectPath });
+  const skills = filterEnabledSkills(listSkills({ projectPath }), {
+    config: globalConfig,
+    projectPath,
+  });
   if (!skills.length) {
     return { contextNote: "", trace: { enabled: true, reason: "no_skills" } };
   }

package/src/core/agent/skills/policy.js

@@ -0,0 +1,128 @@
+// Skills enable/disable policy — scope-aware gating shared by every consumer.
+//
+// A skill can be turned off per scope. A "scope" is either the super-agent /
+// no-project baseline ("default") or a specific project (keyed by its absolute
+// path). Config lives at:
+//
+//   config.skills.policy["default"]        = { "<slug>": true|false, ... }
+//   config.skills.policy["<projectPath>"]  = { "<slug>": true|false, ... }
+//
+// A boolean under a scope is an explicit override; an absent slug inherits.
+// Empty/missing policy = every skill enabled (the pre-feature behavior), so this
+// is fully backward compatible.
+//
+// PRIVATE skills (source "builtin") are APX's own shipped skills. They are
+// always active and can never be disabled or deleted — the UI shows them locked.
+//
+// Effective enabled(skill, projectPath):
+//   1. builtin source                → true (private, locked)
+//   2. project scope explicit value  → that value
+//   3. "default" scope explicit value→ that value
+//   4. otherwise                     → true
+
+export const DEFAULT_SCOPE = "default";
+
+// Sources whose skills ship with apx and are always active.
+const PRIVATE_SOURCES = new Set(["builtin"]);
+
+/** True for APX's own built-in skills — always active, never disableable. */
+export function isPrivateSkill(skill) {
+  return PRIVATE_SOURCES.has(skill?.source);
+}
+
+/** Normalize a project path (or nothing) into a policy scope key. */
+export function resolveScopeKey(projectPath) {
+  const p = typeof projectPath === "string" ? projectPath.trim() : "";
+  return p || DEFAULT_SCOPE;
+}
+
+function policyMap(config) {
+  const p = config?.skills?.policy;
+  return p && typeof p === "object" ? p : {};
+}
+
+function scopeOverride(config, scopeKey, slug) {
+  const scope = policyMap(config)[scopeKey];
+  if (!scope || typeof scope !== "object") return undefined;
+  const v = scope[slug];
+  return typeof v === "boolean" ? v : undefined;
+}
+
+/**
+ * Resolve whether a skill is enabled for the given scope.
+ * @param {{slug:string, source?:string}} skill
+ * @param {{config?:object, projectPath?:string}} ctx
+ * @returns {boolean}
+ */
+export function isSkillEnabled(skill, { config, projectPath } = {}) {
+  if (isPrivateSkill(skill)) return true;
+  const slug = skill?.slug;
+  if (!slug) return true;
+
+  const scopeKey = resolveScopeKey(projectPath);
+  if (scopeKey !== DEFAULT_SCOPE) {
+    const own = scopeOverride(config, scopeKey, slug);
+    if (own !== undefined) return own;
+  }
+  const base = scopeOverride(config, DEFAULT_SCOPE, slug);
+  if (base !== undefined) return base;
+  return true;
+}
+
+/** Keep only the skills enabled for the given scope. */
+export function filterEnabledSkills(skills, ctx = {}) {
+  if (!Array.isArray(skills)) return [];
+  return skills.filter((s) => isSkillEnabled(s, ctx));
+}
+
+/**
+ * Annotate skills for a UI client: adds `enabled`, `private`, and `overridden`
+ * (whether *this* scope holds an explicit override, ignoring inheritance).
+ */
+export function annotateSkills(skills, { config, projectPath } = {}) {
+  if (!Array.isArray(skills)) return [];
+  const scopeKey = resolveScopeKey(projectPath);
+  return skills.map((s) => {
+    const priv = isPrivateSkill(s);
+    const own = priv ? undefined : scopeOverride(config, scopeKey, s.slug);
+    return {
+      ...s,
+      private: priv,
+      enabled: isSkillEnabled(s, { config, projectPath }),
+      overridden: own !== undefined,
+    };
+  });
+}
+
+/**
+ * Set (or clear) a skill's enabled override for a scope. Mutates and returns the
+ * config object. `enabled === null|undefined` clears the override (back to
+ * inherit). Private/builtin skills cannot be overridden.
+ *
+ * @param {object} config          the global config (mutated in place)
+ * @param {object} args
+ * @param {string} args.slug
+ * @param {boolean|null} args.enabled
+ * @param {string=} args.scope     scope key ("default" or a project path)
+ * @param {string=} args.projectPath alternative to scope; normalized to a key
+ */
+export function setSkillEnabled(config, { slug, enabled, scope, projectPath } = {}) {
+  if (!slug) throw new Error("setSkillEnabled: slug required");
+  const scopeKey = scope ? resolveScopeKey(scope) : resolveScopeKey(projectPath);
+
+  config.skills = config.skills || {};
+  config.skills.policy = config.skills.policy || {};
+  const map = config.skills.policy;
+
+  if (enabled === null || enabled === undefined) {
+    if (map[scopeKey]) {
+      delete map[scopeKey][slug];
+      if (Object.keys(map[scopeKey]).length === 0) delete map[scopeKey];
+    }
+    return config;
+  }
+
+  map[scopeKey] = map[scopeKey] || {};
+  map[scopeKey][slug] = !!enabled;
+  return config;
+}

package/src/core/agent/super-agent.js

@@ -1,6 +1,7 @@
 // Super-agent: daemon-level action agent for Telegram, TUI, desktop, routines.
 import { createToolSession, buildLazyToolsBlock, makeToolHandlers } from "#core/agent/tools/registry.js";
 import { listSkills } from "#core/agent/skills/loader.js";
+import { filterEnabledSkills } from "#core/agent/skills/policy.js";
 import {
   runAgent,
   buildSuperAgentSystem,
@@ -97,10 +98,16 @@ export async function runSuperAgent({
   // noTools callers (summarize/ask) get no session — text only.
   const toolSession = noTools ? null : createToolSession(channel, { allowedTools });
 
+  // Scope the catalog hint to the skills enabled for this project (or the
+  // super-agent baseline when no project). Built-in/private skills always pass.
+  const projectPath = channelMeta?.projectPath;
+  const scopedListSkills = (opts = {}) =>
+    filterEnabledSkills(listSkills(opts), { config: globalConfig, projectPath });
+
   const system = buildSuperAgentSystem({
     globalConfig,
     projects,
-    listSkills,
+    listSkills: scopedListSkills,
     contextNote,
     channel,
     channelMeta,

package/src/core/agent/tools/handlers/list-skills.js

@@ -1,5 +1,5 @@
 import { listSkills, SKILL_LOCATIONS } from "#core/agent/skills/loader.js";
-import { condenseSkillDescription } from "#core/agent/skills/index.js";
+import { condenseSkillDescription, filterEnabledSkills } from "#core/agent/skills/index.js";
 
 export default {
   name: "list_skills",
@@ -20,8 +20,11 @@ export default {
       },
     },
   },
-  makeHandler: () => ({ project_path } = {}) => {
-    const skills = listSkills({ projectPath: project_path });
+  makeHandler: (ctx = {}) => ({ project_path } = {}) => {
+    const skills = filterEnabledSkills(
+      listSkills({ projectPath: project_path }),
+      { config: ctx.globalConfig, projectPath: project_path },
+    );
     return {
       ok: true,
       count: skills.length,

package/src/core/agent/tools/handlers/load-skill.js

@@ -1,4 +1,5 @@
 import { loadSkill } from "#core/agent/skills/loader.js";
+import { isSkillEnabled } from "#core/agent/skills/policy.js";
 
 export default {
   name: "load_skill",
@@ -24,8 +25,14 @@ export default {
       },
     },
   },
-  makeHandler: () => ({ slug, project_path } = {}) => {
+  makeHandler: (ctx = {}) => ({ slug, project_path } = {}) => {
     if (!slug) throw new Error("load_skill: slug required");
-    return loadSkill(slug, { projectPath: project_path });
+    const skill = loadSkill(slug, { projectPath: project_path });
+    if (!isSkillEnabled(skill, { config: ctx.globalConfig, projectPath: project_path })) {
+      throw new Error(
+        `skill "${slug}" is disabled for this scope. Enable it in Settings → Skills, or pick another.`,
+      );
+    }
+    return skill;
   },
 };

package/src/core/apc/paths.js

@@ -18,6 +18,7 @@ export const APC_SKILLS_DIR = "skills";
 export const APC_COMMANDS_DIR = "commands";
 export const APC_NOTES_DIR = "notes";
 export const APC_MCPS_FILE = "mcps.json";
+export const APC_ORGANIZATION_FILE = "organization.json";
 export const APC_REMOVED_FILE = ".removed.json";
 export const AGENTS_MD = "AGENTS.md";
 
@@ -77,6 +78,12 @@ export function apcMcpsFile(root) {
   return path.join(root, APC_DIR, APC_MCPS_FILE);
 }
 
+// Org structure (areas + roles) for company/enterprise projects. Committed,
+// no secrets — travels with the project like agents do.
+export function apcOrganizationFile(root) {
+  return path.join(root, APC_DIR, APC_ORGANIZATION_FILE);
+}
+
 export function agentsMdFile(root) {
   return path.join(root, AGENTS_MD);
 }

package/src/core/stores/organization.js

@@ -0,0 +1,152 @@
+// Organization structure (areas + roles) for a project.
+//
+// Only meaningful for "company"/enterprise-shaped projects, but the store is
+// generic: any project can carry an org chart. Persisted as committed JSON at
+//   <root>/.apc/organization.json
+// so it travels with the project and is diffable (same model as agents). No
+// secrets ever live here.
+//
+// Shape on disk:
+//   {
+//     "areas": [{ slug, name, goal }],
+//     "roles": [{ slug, name, area, description }]
+//   }
+//
+// `role.area` references an area slug (or null for a general/unassigned role).
+// Deleting an area detaches its roles (sets their `area` to null) rather than
+// cascading a delete — losing a role definition because its grouping changed
+// would be surprising.
+import fs from "node:fs";
+import path from "node:path";
+import { apcOrganizationFile } from "../apc/paths.js";
+
+export const ORG_SLUG_RE = /^[a-z][a-z0-9_-]*$/;
+
+// Derive a slug from a free-text name (kebab-case). Mirrors the front-end's
+// auto-slug behavior so a name typed in either surface yields the same slug.
+export function slugifyName(name) {
+  return String(name || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .replace(/-{2,}/g, "-");
+}
+
+function emptyOrg() {
+  return { areas: [], roles: [] };
+}
+
+export function readOrganization(root) {
+  const file = apcOrganizationFile(root);
+  if (!fs.existsSync(file)) return emptyOrg();
+  try {
+    const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+    return {
+      areas: Array.isArray(raw.areas) ? raw.areas : [],
+      roles: Array.isArray(raw.roles) ? raw.roles : [],
+    };
+  } catch {
+    // A corrupt file shouldn't take down the whole project view.
+    return emptyOrg();
+  }
+}
+
+function writeOrganization(root, org) {
+  const file = apcOrganizationFile(root);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(org, null, 2) + "\n");
+  return org;
+}
+
+function normSlug(input, fallbackName) {
+  const raw = input && String(input).trim() ? input : slugifyName(fallbackName);
+  const slug = slugifyName(raw);
+  if (!slug || !ORG_SLUG_RE.test(slug)) {
+    throw new Error(`invalid slug: ${slug || "(empty)"}`);
+  }
+  return slug;
+}
+
+// ─────────────────────────────── Areas ─────────────────────────────────────
+
+export function createArea(root, { name, slug, goal } = {}) {
+  if (!name || !String(name).trim()) throw new Error("area name required");
+  const org = readOrganization(root);
+  const areaSlug = normSlug(slug, name);
+  if (org.areas.some((a) => a.slug === areaSlug))
+    throw new Error(`area ${areaSlug} already exists`);
+  const area = { slug: areaSlug, name: String(name).trim(), goal: goal ? String(goal) : null };
+  org.areas.push(area);
+  writeOrganization(root, org);
+  return area;
+}
+
+export function updateArea(root, slug, patch = {}) {
+  const org = readOrganization(root);
+  const area = org.areas.find((a) => a.slug === slug);
+  if (!area) return null;
+  if (patch.name !== undefined) area.name = String(patch.name).trim();
+  if (patch.goal !== undefined) area.goal = patch.goal ? String(patch.goal) : null;
+  writeOrganization(root, org);
+  return area;
+}
+
+export function removeArea(root, slug) {
+  const org = readOrganization(root);
+  const idx = org.areas.findIndex((a) => a.slug === slug);
+  if (idx === -1) return false;
+  org.areas.splice(idx, 1);
+  // Detach roles that pointed at this area (see header note).
+  for (const r of org.roles) if (r.area === slug) r.area = null;
+  writeOrganization(root, org);
+  return true;
+}
+
+// ─────────────────────────────── Roles ─────────────────────────────────────
+
+export function createRole(root, { name, slug, area, description } = {}) {
+  if (!name || !String(name).trim()) throw new Error("role name required");
+  const org = readOrganization(root);
+  const roleSlug = normSlug(slug, name);
+  if (org.roles.some((r) => r.slug === roleSlug))
+    throw new Error(`role ${roleSlug} already exists`);
+  const areaSlug = area ? String(area) : null;
+  if (areaSlug && !org.areas.some((a) => a.slug === areaSlug))
+    throw new Error(`area ${areaSlug} not found`);
+  const role = {
+    slug: roleSlug,
+    name: String(name).trim(),
+    area: areaSlug,
+    description: description ? String(description) : null,
+  };
+  org.roles.push(role);
+  writeOrganization(root, org);
+  return role;
+}
+
+export function updateRole(root, slug, patch = {}) {
+  const org = readOrganization(root);
+  const role = org.roles.find((r) => r.slug === slug);
+  if (!role) return null;
+  if (patch.name !== undefined) role.name = String(patch.name).trim();
+  if (patch.description !== undefined)
+    role.description = patch.description ? String(patch.description) : null;
+  if (patch.area !== undefined) {
+    const areaSlug = patch.area ? String(patch.area) : null;
+    if (areaSlug && !org.areas.some((a) => a.slug === areaSlug))
+      throw new Error(`area ${areaSlug} not found`);
+    role.area = areaSlug;
+  }
+  writeOrganization(root, org);
+  return role;
+}
+
+export function removeRole(root, slug) {
+  const org = readOrganization(root);
+  const idx = org.roles.findIndex((r) => r.slug === slug);
+  if (idx === -1) return false;
+  org.roles.splice(idx, 1);
+  writeOrganization(root, org);
+  return true;
+}

package/src/core/stores/project-files.js

@@ -0,0 +1,199 @@
+// Project file browser — a safe, sandboxed view of a project's own files.
+//
+// Powers the web /files browser and the /docs editor (same store, different
+// root). Everything is resolved *inside* the project root; any path that would
+// escape it throws. This is intentionally NOT a general filesystem API — it
+// only ever touches files under one project.
+//
+// Two roots matter:
+//   - project root  — the repo directory (whole-project /files browser)
+//   - docs root      — a subfolder (config `docs.root`, default "docs") used by
+//                      the /docs editor, so specs/casework live in one place
+//                      (like Appsi's work/ folder of case folders).
+//
+// Reads classify by extension: text is returned inline (utf8); images under a
+// size cap are returned base64 so the authenticated JSON API can render them
+// without a separate unauthenticated asset route; anything else is reported as
+// binary with no body (the UI shows metadata + a download affordance).
+import fs from "node:fs";
+import path from "node:path";
+
+// Directories that are never useful to browse and would blow the node budget.
+const SKIP_DIRS = new Set([
+  "node_modules", ".git", "dist", "build", ".next", ".turbo", ".nuxt",
+  "coverage", ".cache", ".venv", "venv", "__pycache__", ".pytest_cache",
+  ".idea", ".vscode", ".DS_Store",
+]);
+
+const TEXT_EXTS = new Set([
+  "md", "markdown", "mdx", "txt", "text", "rst", "adoc",
+  "js", "jsx", "ts", "tsx", "mjs", "cjs", "json", "jsonc", "json5",
+  "css", "scss", "sass", "less", "html", "htm", "xml", "svg", "vue", "svelte",
+  "py", "rb", "go", "rs", "java", "kt", "c", "h", "cpp", "hpp", "cc",
+  "cs", "php", "swift", "sh", "bash", "zsh", "fish", "sql", "graphql", "gql",
+  "yml", "yaml", "toml", "ini", "cfg", "conf", "env", "properties",
+  "csv", "tsv", "log", "gitignore", "dockerignore", "dockerfile", "makefile",
+]);
+
+const IMAGE_EXTS = new Set(["png", "jpg", "jpeg", "gif", "webp", "svg", "bmp", "ico", "avif"]);
+
+const IMAGE_MIME = {
+  png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif",
+  webp: "image/webp", svg: "image/svg+xml", bmp: "image/bmp", ico: "image/x-icon",
+  avif: "image/avif",
+};
+
+// Guardrails.
+const MAX_NODES = 4000;         // total tree entries returned
+const MAX_TEXT_BYTES = 2_000_000;  // 2 MB inline text ceiling
+const MAX_IMAGE_BYTES = 5_000_000; // 5 MB base64 image ceiling
+
+function extOf(name) {
+  const base = name.toLowerCase();
+  if (base === "dockerfile" || base === "makefile") return base;
+  const dot = base.lastIndexOf(".");
+  return dot === -1 ? "" : base.slice(dot + 1);
+}
+
+export function classifyKind(name) {
+  const ext = extOf(name);
+  if (IMAGE_EXTS.has(ext)) return "image";
+  if (ext === "md" || ext === "markdown" || ext === "mdx") return "markdown";
+  if (TEXT_EXTS.has(ext)) return "text";
+  return "binary";
+}
+
+// Resolve `rel` inside `base`, refusing anything that escapes the sandbox.
+function resolveWithin(base, rel = "") {
+  const root = path.resolve(base);
+  const clean = String(rel || "").replace(/^[/\\]+/, "");
+  const abs = path.resolve(root, clean);
+  if (abs !== root && !abs.startsWith(root + path.sep)) {
+    throw new Error("path escapes the project root");
+  }
+  return { root, abs };
+}
+
+// The docs root for a project (config.docs.root, default "docs"), as a subpath
+// relative to the project root. Sanitized so it can't escape.
+export function docsSubdir(config) {
+  const raw = config?.docs?.root;
+  const sub = raw && typeof raw === "string" ? raw : "docs";
+  return sub.replace(/^[/\\]+/, "").replace(/\.\.(?:[/\\]|$)/g, "");
+}
+
+// Recursively build a nested tree under `absDir`. Dirs first, then files, each
+// alphabetical. `relPrefix` is the path relative to the sandbox root, which is
+// what callers pass back to read/write.
+function walk(absDir, relPrefix, budget) {
+  let entries;
+  try {
+    entries = fs.readdirSync(absDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const dirs = [];
+  const files = [];
+  for (const ent of entries) {
+    const name = ent.name;
+    if (name.startsWith(".")) continue;      // hide dotfiles/dirs
+    if (ent.isDirectory() && SKIP_DIRS.has(name)) continue;
+    (ent.isDirectory() ? dirs : files).push(ent);
+  }
+  dirs.sort((a, b) => a.name.localeCompare(b.name));
+  files.sort((a, b) => a.name.localeCompare(b.name));
+
+  const out = [];
+  for (const ent of [...dirs, ...files]) {
+    if (budget.count >= MAX_NODES) {
+      budget.truncated = true;
+      break;
+    }
+    budget.count += 1;
+    const rel = relPrefix ? `${relPrefix}/${ent.name}` : ent.name;
+    if (ent.isDirectory()) {
+      out.push({ name: ent.name, path: rel, type: "dir", children: walk(path.join(absDir, ent.name), rel, budget) });
+    } else {
+      out.push({ name: ent.name, path: rel, type: "file", kind: classifyKind(ent.name) });
+    }
+  }
+  return out;
+}
+
+// List a tree. `opts.subdir` scopes the sandbox to a subfolder (used for docs).
+// Returns { root, subdir, tree, truncated }. A missing dir yields an empty tree
+// rather than an error — the UI treats that as "nothing here yet".
+export function listTree(projectRoot, opts = {}) {
+  const subdir = opts.subdir ? String(opts.subdir) : "";
+  const { abs } = resolveWithin(projectRoot, subdir);
+  const budget = { count: 0, truncated: false };
+  const tree = fs.existsSync(abs) && fs.statSync(abs).isDirectory()
+    ? walk(abs, "", budget)
+    : [];
+  return { root: projectRoot, subdir, tree, truncated: budget.truncated };
+}
+
+// Read a single file. `opts.subdir` scopes the sandbox (docs). Returns metadata
+// plus the body when it's text/image; binary bodies are omitted.
+export function readFile(projectRoot, relPath, opts = {}) {
+  const base = opts.subdir ? path.join(projectRoot, opts.subdir) : projectRoot;
+  const { abs } = resolveWithin(base, relPath);
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) return null;
+  const stat = fs.statSync(abs);
+  const name = path.basename(abs);
+  const kind = classifyKind(name);
+  const common = {
+    path: relPath.replace(/^[/\\]+/, ""),
+    name,
+    kind,
+    size: stat.size,
+    modified: stat.mtime.toISOString(),
+  };
+  if (kind === "image") {
+    if (stat.size > MAX_IMAGE_BYTES) return { ...common, encoding: "binary", content: null, too_large: true };
+    const ext = extOf(name);
+    return {
+      ...common,
+      encoding: "base64",
+      mime: IMAGE_MIME[ext] || "application/octet-stream",
+      content: fs.readFileSync(abs).toString("base64"),
+    };
+  }
+  if (kind === "binary") {
+    return { ...common, encoding: "binary", content: null };
+  }
+  if (stat.size > MAX_TEXT_BYTES) {
+    return { ...common, encoding: "binary", content: null, too_large: true };
+  }
+  return { ...common, encoding: "utf8", content: fs.readFileSync(abs, "utf8") };
+}
+
+// Write (create or overwrite) a text file, creating parent dirs as needed.
+export function writeFile(projectRoot, relPath, content, opts = {}) {
+  const base = opts.subdir ? path.join(projectRoot, opts.subdir) : projectRoot;
+  const { abs } = resolveWithin(base, relPath);
+  if (typeof content !== "string") throw new Error("content must be a string");
+  if (fs.existsSync(abs) && fs.statSync(abs).isDirectory())
+    throw new Error("path is a directory");
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, content);
+  return { ok: true, path: relPath.replace(/^[/\\]+/, ""), bytes: Buffer.byteLength(content, "utf8") };
+}
+
+// Create a directory (mkdir -p).
+export function makeDir(projectRoot, relPath, opts = {}) {
+  const base = opts.subdir ? path.join(projectRoot, opts.subdir) : projectRoot;
+  const { abs } = resolveWithin(base, relPath);
+  fs.mkdirSync(abs, { recursive: true });
+  return { ok: true, path: relPath.replace(/^[/\\]+/, "") };
+}
+
+// Delete a file or directory (recursive). Refuses to delete the sandbox root.
+export function removeEntry(projectRoot, relPath, opts = {}) {
+  const base = opts.subdir ? path.join(projectRoot, opts.subdir) : projectRoot;
+  const { root, abs } = resolveWithin(base, relPath);
+  if (abs === root) throw new Error("refusing to delete the root");
+  if (!fs.existsSync(abs)) return false;
+  fs.rmSync(abs, { recursive: true, force: true });
+  return true;
+}