@schlessera/brain-ui-server 0.27.0 → 0.28.0

package/src/skills/manager.ts

@@ -0,0 +1,258 @@
+/**
+ * Custom-skill management over the brain repo's canonical skill home.
+ *
+ * The store IS the filesystem convention `brain skills sync` already defines:
+ *
+ * - `.agents/skills/<name>` as a REAL directory = a user's custom skill —
+ *   the local layer, highest discovery precedence, never touched by sync,
+ *   inside the brain repo so it persists across deployments and rides the
+ *   repo's own git backup.
+ * - `.agents/skills/<name>` as a SYMLINK = a package skill (core or module),
+ *   materialized by sync. Read-only here: managed by the packages.
+ * - `.agents/skills-disabled/<name>` = a custom skill parked out of
+ *   discovery. Disable is a directory move, so it applies to EVERY backend
+ *   at once — after a sync, the claude/pi/codex/gemini emitters prune their
+ *   links and the AGENTS.md index drops the row.
+ *
+ * After every mutation the caller runs `brain skills sync` so all agent
+ * integration dirs and the AGENTS.md index block follow the canonical home.
+ *
+ * Security posture: names are strictly validated (no traversal), mutations
+ * refuse to operate through symlinks (a package skill can never be edited or
+ * deleted from here), and content is size-capped. The routes sit behind the
+ * /api auth guard — this surface configures what the agent does.
+ */
+
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  readlinkSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "fs";
+import { join, resolve } from "path";
+import matter from "gray-matter";
+
+/** Agent Skills standard: lowercase kebab, no traversal, bounded. */
+const NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/** A SKILL.md past this is not a skill, it's a document dump. */
+export const MAX_SKILL_CONTENT_BYTES = 128 * 1024;
+
+export interface SkillEntry {
+  /** Directory name (= the skill's identity for enable/disable/remove). */
+  name: string;
+  /** Frontmatter description, or empty when unparseable. */
+  description: string;
+  /** Where the skill comes from; only "custom" entries are editable. */
+  source: "builtin" | "custom";
+  enabled: boolean;
+  /** Set when the SKILL.md failed to parse — shown, not hidden. */
+  warning?: string;
+}
+
+export interface SkillDetail extends SkillEntry {
+  content: string;
+  /** Files in the skill directory besides SKILL.md (repo-relative names). */
+  extraFiles: string[];
+}
+
+export class SkillValidationError extends Error {}
+export class SkillNotFoundError extends Error {}
+export class SkillConflictError extends Error {}
+
+export interface SkillManager {
+  list(): SkillEntry[];
+  get(name: string): SkillDetail;
+  create(name: string, content: string): SkillEntry;
+  update(name: string, content: string): SkillEntry;
+  setEnabled(name: string, enabled: boolean): SkillEntry;
+  remove(name: string): void;
+}
+
+export function createSkillManager(brainPath: string): SkillManager {
+  const enabledDir = join(brainPath, ".agents", "skills");
+  const disabledDir = join(brainPath, ".agents", "skills-disabled");
+
+  function assertValidName(name: string): void {
+    if (!NAME_PATTERN.test(name)) {
+      throw new SkillValidationError(
+        "Skill name must be lowercase kebab-case (a-z, 0-9, hyphens), max 64 chars."
+      );
+    }
+  }
+
+  /** lstat without following; null when absent. */
+  function kindOf(path: string): "dir" | "symlink" | "other" | null {
+    try {
+      const st = lstatSync(path);
+      if (st.isSymbolicLink()) return "symlink";
+      if (st.isDirectory()) return "dir";
+      return "other";
+    } catch {
+      return null;
+    }
+  }
+
+  function parseSkillFile(dir: string): { description: string; warning?: string } {
+    const file = join(dir, "SKILL.md");
+    if (!existsSync(file)) {
+      return { description: "", warning: "SKILL.md is missing" };
+    }
+    try {
+      const data = matter(readFileSync(file, "utf-8")).data as Record<string, unknown>;
+      const description = typeof data.description === "string" ? data.description : "";
+      if (!description) return { description: "", warning: "frontmatter has no description" };
+      return { description };
+    } catch (e) {
+      return {
+        description: "",
+        warning: `frontmatter does not parse: ${e instanceof Error ? e.message : String(e)}`,
+      };
+    }
+  }
+
+  function entryFor(name: string, dir: string, source: "builtin" | "custom", enabled: boolean): SkillEntry {
+    const parsed = parseSkillFile(dir);
+    return {
+      name,
+      description: parsed.description,
+      source,
+      enabled,
+      ...(parsed.warning ? { warning: parsed.warning } : {}),
+    };
+  }
+
+  /** Validate content as a plausible skill for directory `name`. */
+  function validateContent(name: string, content: string): void {
+    if (Buffer.byteLength(content, "utf-8") > MAX_SKILL_CONTENT_BYTES) {
+      throw new SkillValidationError(
+        `SKILL.md exceeds ${MAX_SKILL_CONTENT_BYTES / 1024}KB.`
+      );
+    }
+    let data: Record<string, unknown>;
+    try {
+      data = matter(content).data as Record<string, unknown>;
+    } catch (e) {
+      throw new SkillValidationError(
+        `Frontmatter does not parse: ${e instanceof Error ? e.message : String(e)}`
+      );
+    }
+    if (data.name !== name) {
+      throw new SkillValidationError(
+        `Frontmatter \`name\` must equal the skill directory name ("${name}").`
+      );
+    }
+    if (typeof data.description !== "string" || !data.description.trim()) {
+      throw new SkillValidationError(
+        "Frontmatter needs a non-empty `description` — it is what makes agents find the skill."
+      );
+    }
+  }
+
+  /** The custom skill's live directory, or throw. Never follows symlinks. */
+  function customDir(name: string): { dir: string; enabled: boolean } {
+    assertValidName(name);
+    const enabled = join(enabledDir, name);
+    const disabled = join(disabledDir, name);
+    if (kindOf(enabled) === "dir") return { dir: enabled, enabled: true };
+    if (kindOf(disabled) === "dir") return { dir: disabled, enabled: false };
+    if (kindOf(enabled) === "symlink") {
+      throw new SkillConflictError(
+        `"${name}" is a package skill (managed by brain-kit); it cannot be edited here.`
+      );
+    }
+    throw new SkillNotFoundError(`No custom skill named "${name}".`);
+  }
+
+  return {
+    list(): SkillEntry[] {
+      const entries: SkillEntry[] = [];
+      if (existsSync(enabledDir)) {
+        for (const entry of readdirSync(enabledDir).sort()) {
+          const p = join(enabledDir, entry);
+          const kind = kindOf(p);
+          if (kind === "symlink") entries.push(entryFor(entry, p, "builtin", true));
+          else if (kind === "dir") entries.push(entryFor(entry, p, "custom", true));
+        }
+      }
+      if (existsSync(disabledDir)) {
+        for (const entry of readdirSync(disabledDir).sort()) {
+          const p = join(disabledDir, entry);
+          if (kindOf(p) === "dir") entries.push(entryFor(entry, p, "custom", false));
+        }
+      }
+      return entries;
+    },
+
+    get(name: string): SkillDetail {
+      assertValidName(name);
+      // Builtins are readable (their content is useful reference) but the
+      // detail is marked read-only via source.
+      const enabledPath = join(enabledDir, name);
+      const kind = kindOf(enabledPath);
+      if (kind === "symlink") {
+        // Follow explicitly for READ only.
+        // resolve, not join: sync writes relative link targets, but a test or
+        // hand-made link may be absolute.
+        const target = resolve(enabledDir, readlinkSync(enabledPath));
+        const content = existsSync(join(target, "SKILL.md"))
+          ? readFileSync(join(target, "SKILL.md"), "utf-8")
+          : "";
+        return { ...entryFor(name, target, "builtin", true), content, extraFiles: [] };
+      }
+      const { dir, enabled } = customDir(name);
+      const content = existsSync(join(dir, "SKILL.md"))
+        ? readFileSync(join(dir, "SKILL.md"), "utf-8")
+        : "";
+      const extraFiles = readdirSync(dir)
+        .filter((f) => f !== "SKILL.md")
+        .sort();
+      return { ...entryFor(name, dir, "custom", enabled), content, extraFiles };
+    },
+
+    create(name: string, content: string): SkillEntry {
+      assertValidName(name);
+      validateContent(name, content);
+      if (kindOf(join(enabledDir, name)) !== null) {
+        throw new SkillConflictError(`A skill named "${name}" already exists.`);
+      }
+      if (kindOf(join(disabledDir, name)) !== null) {
+        throw new SkillConflictError(`A disabled skill named "${name}" already exists.`);
+      }
+      const dir = join(enabledDir, name);
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(join(dir, "SKILL.md"), content, "utf-8");
+      return entryFor(name, dir, "custom", true);
+    },
+
+    update(name: string, content: string): SkillEntry {
+      const { dir, enabled } = customDir(name);
+      validateContent(name, content);
+      writeFileSync(join(dir, "SKILL.md"), content, "utf-8");
+      return entryFor(name, dir, "custom", enabled);
+    },
+
+    setEnabled(name: string, enabled: boolean): SkillEntry {
+      const current = customDir(name);
+      if (current.enabled === enabled) {
+        return entryFor(name, current.dir, "custom", enabled);
+      }
+      const target = enabled ? join(enabledDir, name) : join(disabledDir, name);
+      if (kindOf(target) !== null) {
+        throw new SkillConflictError(`"${name}" already exists at the target location.`);
+      }
+      mkdirSync(enabled ? enabledDir : disabledDir, { recursive: true });
+      renameSync(current.dir, target);
+      return entryFor(name, target, "custom", enabled);
+    },
+
+    remove(name: string): void {
+      const { dir } = customDir(name);
+      rmSync(dir, { recursive: true, force: true });
+    },
+  };
+}

package/src/ws/bridge.ts

@@ -65,6 +65,16 @@ export function makeBridge(
       }
     },
     requestPermission: (req) => {
+      // A remembered "always allow" answers grantable tool requests without
+      // a card. NEVER for kind "command" — those are destructive-pattern
+      // confirmations for tools that are already auto-allowed, and
+      // remembering them would silently disable the seatbelt.
+      if (
+        req.kind !== "command" &&
+        host.toolPermissions?.isAutoAllowed(req.toolName)
+      ) {
+        return Promise.resolve({ behavior: "allow" });
+      }
       if (!host.clients.hasClients()) {
         // Not a failure — the card is parked and re-delivered on reconnect
         // (see resendPendingInteractive) — but the wait was invisible before
@@ -83,6 +93,7 @@ export function makeBridge(
             toolName: req.toolName,
             input: req.input,
             description: req.description,
+            ...(req.kind ? { kind: req.kind } : {}),
           },
           turn,
           turnId

package/src/ws/connection.ts

@@ -24,6 +24,7 @@ function resendPendingInteractive(host: WsHost, ws: WSContextType): void {
           toolName: p.request.toolName,
           input: p.request.input,
           description: p.request.description,
+          ...(p.request.kind ? { kind: p.request.kind } : {}),
         },
         p.turn,
         p.turnId

package/src/ws/dispatch.ts

@@ -139,6 +139,11 @@ export async function handleClientMessage(
       const pending = coordinator.pendingApprovals.get(msg.toolUseId);
       if (pending && turnIdMatches(pending, msg.turnId, requireEcho)) {
         coordinator.pendingApprovals.delete(msg.toolUseId);
+        // Remember-on-approve. Kind "command" never persists (the client
+        // hides the option, but the wire is not trusted to enforce policy).
+        if (msg.always && pending.request.kind !== "command") {
+          host.toolPermissions?.add(pending.request.toolName);
+        }
         pending.resolve(
           msg.updatedInput
             ? { behavior: "allow", updatedInput: msg.updatedInput }

package/src/ws/host.ts

@@ -81,6 +81,20 @@ export interface WsHostOptions {
    * most existing tests want.
    */
   activity?: ActivityRuntime;
+  /**
+   * The user's remembered "always allow" tool grants. Optional: a host
+   * without one never auto-answers and never persists an `always` approval —
+   * every card stays per-use (what existing tests expect).
+   */
+  toolPermissions?: ToolPermissions;
+}
+
+/** The remembered per-tool auto-allow store the ws layer consults. */
+export interface ToolPermissions {
+  /** Whether requests for this tool are answered "allow" without a card. */
+  isAutoAllowed(toolName: string): boolean;
+  /** Remember this tool as always allowed. */
+  add(toolName: string): void;
 }
 
 /** Identity of one turn, as it appears on a log record. */
@@ -119,6 +133,7 @@ export class WsHost {
   readonly observability: Observability;
   readonly wsRate: { ratePerSecond: number; burst: number } | null;
   readonly activity: ActivityRuntime | null;
+  readonly toolPermissions: ToolPermissions | null;
   /** Scoped instruments, resolved once — `[ws]` is the existing log prefix. */
   readonly log: ReturnType<Observability["logger"]>;
   private readonly framesDropped: ReturnType<
@@ -148,6 +163,7 @@ export class WsHost {
     this.wsRate =
       options.wsRate && options.wsRate.ratePerSecond > 0 ? options.wsRate : null;
     this.activity = options.activity ?? null;
+    this.toolPermissions = options.toolPermissions ?? null;
     this.log = this.observability.logger("ws");
     const meter = this.observability.meter("ws");
     this.framesDropped = meter.createCounter("ws.frames.dropped", {