@bevel-software/platform-core-backend 0.14.0 → 0.19.0

package/src/modules/plugins/plugins.service.ts

@@ -1,12 +1,13 @@
-import path from 'node:path';
 import fs from 'node:fs/promises';
-import type { Dirent } from 'node:fs';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('plugins');
+import path from 'node:path';
 import {
   DEFAULT_BRANCH,
-  PLUGINS_DIR,
-  pluginOfPath,
-  isPersonalPluginFolder,
 } from '@bevel-software/platform-shared';
+import { isPrivateAccessMd } from '../access-model/access-grammar.js';
+import { isAbsence } from '../../shared/fs.contract.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
@@ -14,9 +15,21 @@ import type { ISkillService } from '../skills/skills.contract.js';
 import type { IToolManualService } from '../tool-manuals/tool-manuals.contract.js';
 import { TtlCache } from '../../shared/ttl-cache.js';
 import type { PluginCatalogEntry, IPluginIndexService } from './plugins.contract.js';
+import type { PluginLinkIndex } from './plugin-links.js';
+import type { PluginSource } from './discovery/plugin-source.js';
 
 const CACHE_TTL_MS = 60_000;
 
+/** What one discovery pass keeps about a plugin, before the counts and verdicts. */
+interface ScannedPlugin {
+  folders: string[];
+  /** The roots it links skills from — see `PluginSummary.linkedRoots`. */
+  linkedRoots: string[];
+  linksAreManaged: boolean;
+  displayName: string;
+  warnings: string[];
+}
+
 /**
  * The plugin index: every plugin folder in the default-branch KB, with its
  * caller-independent totals and access principals.
@@ -51,7 +64,15 @@ export class PluginIndexService implements IPluginIndexService {
     private readonly skillService: ISkillService,
     private readonly toolManualService: IToolManualService,
     private readonly kbDirName: string,
+    /** Where plugins come from — the one discovery every catalog shares. */
+    private readonly source: PluginSource,
     now: () => number = Date.now,
+    /**
+     * The link index, when the deployment has one: a plugin's skill count is
+     * then inline PLUS linked. Optional so hosts composing their own service
+     * set (and older tests) keep the inline-only count.
+     */
+    private readonly links?: PluginLinkIndex,
   ) {
     this.cache = new TtlCache(CACHE_TTL_MS, now);
   }
@@ -63,6 +84,9 @@ export class PluginIndexService implements IPluginIndexService {
   async catalog(): Promise<PluginCatalogEntry[]> {
     const cached = this.cache.get();
     if (cached) return cached;
+    // See `TtlCache.begin`: taken before the read so an `invalidate()` that
+    // lands mid-build discards this result instead of being overwritten by it.
+    const token = this.cache.begin();
     const entries = await this.build();
     // A failed scan and a KB with genuinely no plugin folders both serve `[]`,
     // but only the second is a fact worth holding for the TTL. Caching the
@@ -72,7 +96,7 @@ export class PluginIndexService implements IPluginIndexService {
     // never arrive in that window. So a degraded read is served, not stored,
     // and the next caller retries.
     if (entries === null) return [];
-    this.cache.set(entries);
+    this.cache.set(entries, token);
     return entries;
   }
 
@@ -94,95 +118,185 @@ export class PluginIndexService implements IPluginIndexService {
       const wsId = (await this.workspaceService.getOrCreateForBranch(DEFAULT_BRANCH)).id;
       const kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
 
-      const folders = await this.scanFolders(kbRoot);
-      if (folders.size === 0) return [];
+      const scanned = await this.scanFolders(kbRoot);
+      if (scanned.size === 0) return [];
+      const folders = new Map([...scanned].map(([name, p]) => [name, p.folders]));
 
-      const [skillCounts, toolCounts] = await Promise.all([
-        this.countSkills(),
-        this.countTools(),
+      const [{ skillCounts, brokenLinkCounts }, toolCounts] = await Promise.all([
+        this.countThroughLinks(folders),
+        this.countTools(scanned),
       ]);
 
       const entries: PluginCatalogEntry[] = [];
       for (const [name, pluginFolders] of folders) {
         // One folder, one access boundary — the folder IS the plugin.
         const [primary] = pluginFolders;
-        const [owners, writers, readers] = await Promise.all([
+        const [owners, writers, readers, isPrivate] = await Promise.all([
           this.accessControl.eligibleOwners(wsId, primary),
           this.accessControl.eligibleWriters(wsId, primary),
           this.accessControl.eligibleReaders(wsId, primary),
+          this.readsAsPrivate(path.join(kbRoot, primary, 'access.md')),
         ]);
         entries.push({
           name,
+          displayName: scanned.get(name)?.displayName ?? name,
           folders: pluginFolders,
+          linkedRoots: scanned.get(name)?.linkedRoots ?? [],
+          linksAreManaged: scanned.get(name)?.linksAreManaged ?? false,
           skillCount: skillCounts.get(name) ?? 0,
           toolCount: toolCounts.get(name) ?? 0,
+          brokenLinks: brokenLinkCounts.get(name) ?? 0,
           owners,
           writers,
           readers,
+          isPrivate,
+          warnings: scanned.get(name)?.warnings ?? [],
         });
       }
       return entries.sort((a, b) => a.name.localeCompare(b.name));
     } catch (err) {
-      console.warn(
-        `[plugins] plugin index unavailable: ${err instanceof Error ? err.message : String(err)}`,
-      );
+      log.warn(`plugin index unavailable: ${err instanceof Error ? err.message : String(err)}`);
       return null;
     }
   }
 
-  /** name → repo-relative plugin folder (always a single-element list). */
-  private async scanFolders(kbRoot: string): Promise<Map<string, string[]>> {
-    const byName = new Map<string, string[]>();
-    let children: Dirent[];
-    try {
-      children = await fs.readdir(path.join(kbRoot, PLUGINS_DIR), { withFileTypes: true });
-    } catch {
-      return byName; // a KB without a `Plugins/` root simply has no plugins
+  /**
+   * name → repo-relative plugin folder (always a single-element list), from
+   * the configured source. Personal folders live under Plugins/ but are not
+   * plugins: one exists per person, private by construction, and listing them
+   * would put a locked row per employee in everyone's index. `exists` is the
+   * source's existence rule (see `DiscoveredPlugin`) — for native plugins,
+   * the `access.md` the class doc describes.
+   */
+  private async scanFolders(kbRoot: string): Promise<Map<string, ScannedPlugin>> {
+    const byName = new Map<string, ScannedPlugin>();
+    const discovered = await this.source.discover(kbRoot);
+    for (const w of discovered.warnings) log.warn(w);
+    for (const plugin of discovered.plugins) {
+      if (plugin.personal || !plugin.exists) continue;
+      byName.set(plugin.name, {
+        folders: [plugin.folder],
+        linkedRoots: plugin.linkedRoots,
+        linksAreManaged: plugin.linksAreManaged,
+        displayName: plugin.displayName,
+        // Discovery prefixes what it says about one plugin with that
+        // plugin's folder; the page names the plugin already, so the
+        // prefix goes. Whatever names no folder (an unreadable registry)
+        // stays in the log alone.
+        warnings: discovered.warnings
+          .filter((w) => w.startsWith(`${plugin.folder}: `) || w.startsWith(`${plugin.folder}/`))
+          .map((w) => w.slice(plugin.folder.length).replace(/^[:/]\s*/, '')),
+      });
     }
-    const candidates = children.filter(
-      (child) =>
-        child.isDirectory() &&
-        !child.name.startsWith('.') &&
-        // Personal folders live under Plugins/ but are not plugins: one exists
-        // per person, private by construction, and listing them would put a
-        // locked row per employee in everyone's index.
-        !isPersonalPluginFolder(child.name),
-    );
-    // A plugin exists exactly when its folder carries an `access.md` (see the
-    // class doc) — stat that file, don't trust the directory.
-    const verdicts = await Promise.all(
-      candidates.map(async (child) => {
-        try {
-          return (await fs.stat(path.join(kbRoot, PLUGINS_DIR, child.name, 'access.md'))).isFile();
-        } catch {
-          return false;
-        }
-      }),
-    );
-    candidates.forEach((child, i) => {
-      if (verdicts[i]) byName.set(child.name, [`${PLUGINS_DIR}/${child.name}`]);
-    });
     return byName;
   }
 
-  private async countSkills(): Promise<Map<string, number>> {
-    // `undefined` is the documented GLOBAL, unfiltered mode — counts are a
-    // property of the plugin, not of who is asking.
-    return bucketByPlugin(await this.skillService.listSkills(undefined));
+  /**
+   * Two counts from ONE read of the link index — the membership is built
+   * once per cold catalog, not once per count: `TtlCache` has no
+   * single-flight, so two concurrent readers of an empty cache would each
+   * discover the tree and resolve every linked skill's access.
+   *
+   *  - `skillCounts`: with links, a skill counts for EVERY plugin that holds
+   *    it — inline in its folder, or linked from a manifest. Personal folders
+   *    are already absent from the membership (they are places, not plugins).
+   *  - `brokenLinkCounts`: how many linked skills each plugin's members
+   *    cannot read — memberships reported as linked but not granted. From the
+   *    UNFILTERED index, so the count reaches the plugin's managers even when
+   *    the missing grant locks them out of the skill too.
+   *
+   * Without a link index: skills bucket by folder, and no link can be broken.
+   */
+  private async countThroughLinks(
+    folders: Map<string, string[]>,
+  ): Promise<{ skillCounts: Map<string, number>; brokenLinkCounts: Map<string, number> }> {
+    const skillCounts = new Map<string, number>();
+    const brokenLinkCounts = new Map<string, number>();
+    if (!this.links) {
+      // `undefined` is the documented GLOBAL, unfiltered mode — counts are a
+      // property of the plugin, not of who is asking.
+      return {
+        skillCounts: bucketByFolder(await this.skillService.listSkills(undefined), folders),
+        brokenLinkCounts,
+      };
+    }
+    for (const memberships of (await this.links.membership()).bySkill.values()) {
+      for (const m of memberships) {
+        skillCounts.set(m.name, (skillCounts.get(m.name) ?? 0) + 1);
+        if (m.linked && !m.granted) brokenLinkCounts.set(m.name, (brokenLinkCounts.get(m.name) ?? 0) + 1);
+      }
+    }
+    return { skillCounts, brokenLinkCounts };
   }
 
-  private async countTools(): Promise<Map<string, number>> {
-    return bucketByPlugin(await this.toolManualService.listAllSummaries());
+  /**
+   * Tools belong to the plugin whose FOLDER holds them — matched by path
+   * prefix against the discovered folders, not by `pluginOfPath`'s
+   * second-segment rule, so a dialect plugin nested three folders deep still
+   * counts the servers its bundle expands.
+   *
+   * And to every plugin one of whose LINKED ROOTS holds them. A root is a
+   * skill folder or a folder of skills, and a `.tool` manual sitting beside
+   * those skills reaches the plugin the same way they do — the plugin's page
+   * lists it, so the plugin's total has to count it. Once per plugin: a root
+   * inside the plugin's own folder says nothing the folder did not say first.
+   *
+   * Without a link index, inline only — the same degradation `countThroughLinks`
+   * makes for skills. A host that composes no link index has asked for totals
+   * that count what each plugin's folder holds, and a catalog that counted a
+   * plugin's linked tools while leaving its linked skills out would describe a
+   * plugin that exists nowhere.
+   */
+  private async countTools(scanned: Map<string, ScannedPlugin>): Promise<Map<string, number>> {
+    const counts = new Map<string, number>();
+    const plugins = [...scanned].map(([name, p]) => ({
+      name,
+      folders: p.folders,
+      roots: this.links ? p.linkedRoots : [],
+    }));
+    const bump = (name: string) => counts.set(name, (counts.get(name) ?? 0) + 1);
+    for (const tool of await this.toolManualService.listAllSummaries()) {
+      const inline = plugins.find((p) => p.folders.some((f) => tool.path.startsWith(`${f}/`)));
+      if (inline) bump(inline.name);
+      for (const p of plugins) {
+        if (p === inline) continue;
+        if (p.roots.some((root) => tool.path.startsWith(`${root}/`))) bump(p.name);
+      }
+    }
+    return counts;
+  }
+
+  /**
+   * What the plugin's own access.md says of itself — see
+   * `PluginCatalogEntry.isPrivate`. Read from disk rather than through the
+   * resolver: the mark reflects the file's frontmatter as written. An
+   * ABSENT file makes no statement (false: a plugin discovered by its
+   * manifest may have no rules yet); any other failure to read it is a real
+   * one and propagates, so the catalog never claims a privacy verdict it
+   * could not inspect — `build` degrades the whole read, as for any fault.
+   */
+  private async readsAsPrivate(accessMdPath: string): Promise<boolean> {
+    try {
+      return isPrivateAccessMd(await fs.readFile(accessMdPath, 'utf8'));
+    } catch (err) {
+      if (isAbsence(err)) return false;
+      throw err;
+    }
   }
 }
 
-/** Count items per plugin folder name; ungrouped items (`null`) count nowhere. */
-function bucketByPlugin(items: { path: string }[]): Map<string, number> {
+/**
+ * Count items per plugin by FOLDER PREFIX against the discovered folders —
+ * not by `pluginOfPath`'s second-segment rule, which would file a nested
+ * plugin's skills under its grouping folder. Items in no plugin count nowhere.
+ */
+function bucketByFolder(items: { path: string }[], folders: Map<string, string[]>): Map<string, number> {
   const counts = new Map<string, number>();
+  const byFolder = [...folders.entries()].map(([name, [folder]]) => ({ name, prefix: `${folder}/` }));
   for (const item of items) {
-    const plugin = pluginOfPath(item.path);
-    if (plugin === null) continue;
-    counts.set(plugin, (counts.get(plugin) ?? 0) + 1);
+    const owner = byFolder.find((f) => item.path.startsWith(f.prefix));
+    if (!owner) continue;
+    counts.set(owner.name, (counts.get(owner.name) ?? 0) + 1);
   }
   return counts;
 }
@@ -191,3 +305,16 @@ function bucketByPlugin(items: { path: string }[]): Map<string, number> {
 export function pluginsWorkspaceId(): string {
   return workspaceIdForBranch(DEFAULT_BRANCH);
 }
+
+/**
+ * A plugin folder's path BELOW the plugins root: `GTM`, or `teams/deep`.
+ *
+ * The key a join request is cut by — its branch, and the row that records it
+ * — so it lives here rather than in any one of the three places that need to
+ * compute it. The whole path, not the basename, so two plugins whose folders
+ * share a basename can never share a branch; and it survives a rename of the
+ * plugin's identity, which moves no folder.
+ */
+export function pluginFolderBelowRoot(folder: string): string {
+  return folder.slice(folder.indexOf('/') + 1);
+}

package/src/modules/plugins/plugins.tools.ts

@@ -0,0 +1,88 @@
+import type { IToolRegistry, UtcpTool } from '../tool-registry/tool.contract.js';
+import { toolDef } from '../tool-helpers/tool-def.js';
+
+/**
+ * The two plugin tools an agent has, both surfaces — DESCRIPTIONS of the
+ * app's own creation endpoints, not a second implementation of them:
+ *
+ *  - `my_plugin`     → `POST /api/plugins/personal`
+ *  - `create_plugin` → `POST /api/plugins`
+ *
+ * The endpoints are the same ones the New plugin button and the first-visit
+ * personal-folder ensure call; they sit behind a gate that admits an agent's
+ * connection key as well as a session (`keyOrSessionAuth`), so one route
+ * serves both. Without these an agent asked to "put my skills in Hexis" had
+ * nowhere to write: the personal folder is created lazily by the web app
+ * under a name derived from the user's id, and a non-admin's plain write
+ * under the plugins root is refused by the root rules.
+ *
+ * Every rule the app enforces — names, reserved prefixes, twins, where a
+ * plugin may go, the one commit — is the endpoint's, so it holds for an
+ * agent exactly as for a person; a refusal comes back as the endpoint's own
+ * 4xx with its message.
+ */
+export function registerPluginsTools(registry: IToolRegistry): void {
+  registry.registerExternalTool(MY_PLUGIN);
+  registry.registerInternalTool(MY_PLUGIN);
+  registry.registerExternalTool(CREATE_PLUGIN);
+  registry.registerInternalTool(CREATE_PLUGIN);
+}
+
+/** The endpoint's answer, `ProvisionedPlugin` — see `PluginProvisionService`. */
+const PROVISIONED_OUTPUT = {
+  type: 'object',
+  properties: {
+    path: { type: 'string', description: 'The plugin folder, repo-relative (e.g. `Plugins/personal-abc`, `Plugins/Teams/GTM`) — the path the file tools address.' },
+    skillsDir: { type: 'string', description: 'Where its skills go: `<path>/skills`. Each skill is a subfolder holding a `SKILL.md`.' },
+    folder: { type: 'string', description: 'The same folder as its path below the plugins root.' },
+    name: { type: 'string', description: 'The plugin identity (its manifest name), as grants and the marketplace spell it.' },
+    displayName: { type: 'string', description: 'What people see it called — the manifest `displayName`, exactly as persisted: for `create_plugin`, the name that was asked for, trimmed; for `my_plugin`, the personal folder\'s own label.' },
+    created: { type: 'boolean', description: 'False when the folder already existed.' },
+  },
+} as const;
+
+export const MY_PLUGIN: UtcpTool = toolDef({
+  name: 'my_plugin',
+  description:
+    "The caller's own private plugin — their personal space in the knowledge base, created on first use. " +
+    'Returns its folder and where skills go inside it (`skillsDir`); write a skill there as ' +
+    '`<skillsDir>/<skill-name>/SKILL.md` with the file tools, opening with the Agent Skills frontmatter ' +
+    '(`name`, `description`, and `metadata.version` such as `"1.0.0"`). Readable only by its owner — not even admins — and ' +
+    'never listed as a shared plugin. Idempotent: calling it again returns the same folder.',
+  path: '/api/plugins/personal',
+  inputs: { type: 'object', properties: {}, additionalProperties: false },
+  outputs: PROVISIONED_OUTPUT,
+  // `write`: both make folders and commit — a read-scoped caller's manual
+  // must not advertise them (see `isWriteTool` in the manual routes).
+  tags: ['plugins', 'skills', 'write'],
+});
+
+export const CREATE_PLUGIN: UtcpTool = toolDef({
+  name: 'create_plugin',
+  description:
+    "Create a shared plugin under the plugins root, exactly as the app's New plugin button does: the caller " +
+    'runs it (read, write and owner), and it is discoverable by everyone so people can ask to join. Pass ' +
+    '`parent` to make it inside an existing grouping folder under the plugins root (e.g. `Teams`); a plugin ' +
+    'cannot be made inside another plugin. Returns the folder and where its skills go. A refusal carries ' +
+    '`error` in words. 4xx means the input will not do: 409 when a plugin of that name (or its identifier) ' +
+    'exists, 422 for a name the knowledge base cannot carry or a parent that may not hold a plugin, 404 when ' +
+    'the parent folder is not there. 503 means the plugin list could not be read completely just now — ' +
+    'nothing is wrong with the input; try again shortly.',
+  path: '/api/plugins',
+  inputs: {
+    type: 'object',
+    properties: {
+      name: { type: 'string', minLength: 1, description: 'The plugin name, e.g. `Design`. Becomes the folder name and the display name people see; its identifier is the kebab-case slug.' },
+      parent: {
+        type: 'string',
+        description: 'Optional grouping folder below the plugins root to create it in, e.g. `Teams` or `Teams/EU`. Omit for the root.',
+      },
+    },
+    required: ['name'],
+    additionalProperties: false,
+  },
+  outputs: PROVISIONED_OUTPUT,
+  // `write`: both make folders and commit — a read-scoped caller's manual
+  // must not advertise them (see `isWriteTool` in the manual routes).
+  tags: ['plugins', 'skills', 'write'],
+});

package/src/modules/plugins/teams.routes.ts

@@ -0,0 +1,129 @@
+import express from 'express';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('teams');
+import { isPersonalPluginDir, isPersonalPluginFolder, pluginOfPath } from '@bevel-software/platform-shared';
+import type { IAccessControl } from '../access/access-control.interface.js';
+import type { ISkillService } from '../skills/skills.contract.js';
+import type { IToolManualService } from '../tool-manuals/tool-manuals.contract.js';
+import type { IPluginIndexService, PluginCatalogEntry } from './plugins.contract.js';
+import { pluginsWorkspaceId } from './plugins.service.js';
+
+/**
+ * What one team can use, by id — the Library's "Your teams" lens.
+ *
+ * A team is a group from the active group source (`groups.yaml`, or the
+ * IdP-synced file), and what it can use is what being IN it lets a person
+ * read: the plugins whose rules admit the group, the skills those plugins
+ * link or hold, a shared skill whose own folder names the group, the tools
+ * declared in an admitted plugin. The verdict is the resolver's own
+ * (`canReadAsGroupBatch`), so a grant reached through a role that lists the
+ * group, or through `plugin/<name>/read` on a skill the group's plugin links,
+ * counts exactly as it does for a member.
+ *
+ * Every id is ALSO gated on the caller: a skill or tool the caller cannot
+ * read is not named here, however the team stands, and a plugin appears only
+ * when the caller could see it on the index (a member, or able to discover
+ * it). The lens never widens what the catalog already shows the caller — it
+ * slices it.
+ *
+ * The list opens with `Everyone`: not a group, the built-in org-wide
+ * principal — what a signed-in person in no group at all can use, which is
+ * what `read: everyone` (or a public plugin) reaches. Same slice, same
+ * caller gate, asked of the resolver as `canReadAsEveryoneBatch`. The name
+ * cannot collide with a group's: `everyone` is reserved by the grammar.
+ */
+export interface TeamAccess {
+  name: string;
+  /** Plugin identities (manifest names) the team's members can read. */
+  plugins: string[];
+  /** Skill names. */
+  skills: string[];
+  /** Tool slugs. */
+  tools: string[];
+}
+
+/** The org-wide entry's name — the built-in `everyone` principal, as the sidebar spells it. */
+export const EVERYONE_TEAM = 'Everyone';
+
+export function createTeamsRoutes(
+  accessControl: IAccessControl,
+  pluginIndex: IPluginIndexService,
+  skillService: Pick<ISkillService, 'listSkills'>,
+  toolManuals: Pick<IToolManualService, 'listAllSummaries'>,
+): express.Router {
+  const router = express.Router();
+
+  router.get('/teams', async (req, res) => {
+    const email = req.userEmail;
+    if (!email) {
+      res.status(401).json({ error: 'Unauthenticated' });
+      return;
+    }
+    try {
+      const wsId = pluginsWorkspaceId();
+      const [{ groups }, catalog, allSkills, allTools] = await Promise.all([
+        accessControl.kbPrincipals(wsId),
+        pluginIndex.catalog(),
+        skillService.listSkills(),
+        toolManuals.listAllSummaries(),
+      ]);
+      // A personal plugin is one person's space, not a team's: it has no
+      // roster and admits nobody, so neither it nor anything inside it can
+      // be a team's to read — whatever a hand-written grant in there says.
+      // One rule for the plugin and for its contents, so the two cannot
+      // disagree.
+      const plugins = catalog.filter((g) => !g.folders.every(isPersonalPluginDir));
+      const skills = allSkills.filter((s) => !inPersonalPlugin(s.path));
+      const tools = allTools.filter((t) => !inPersonalPlugin(t.path));
+      const folderProbes = plugins.flatMap((g) => g.folders);
+      const discoverProbes = folderProbes.map(accessMdOf);
+      const skillProbes = skills.map((s) => skillMdOf(s.path));
+      const toolProbes = tools.map((t) => t.path);
+      const probes = [...new Set([...folderProbes, ...discoverProbes, ...skillProbes, ...toolProbes])];
+
+      const caller = await accessControl.canReadBatch(wsId, email, probes);
+      const callerReads = (p: string) => caller.get(p) === true;
+      const callerSeesPlugin = (g: PluginCatalogEntry) =>
+        g.folders.some((f) => callerReads(f) || callerReads(accessMdOf(f)));
+
+      /** One entry: what `verdicts` reads, cut to what the caller sees. */
+      const slice = (name: string, verdicts: Map<string, boolean>): TeamAccess => {
+        const reads = (p: string) => verdicts.get(p) === true;
+        return {
+          name,
+          plugins: plugins
+            .filter((g) => g.folders.some(reads) && callerSeesPlugin(g))
+            .map((g) => g.name),
+          skills: skills
+            .filter((s) => reads(skillMdOf(s.path)) && callerReads(skillMdOf(s.path)))
+            .map((s) => s.name),
+          tools: tools.filter((t) => reads(t.path) && callerReads(t.path)).map((t) => t.slug),
+        };
+      };
+
+      const teams: TeamAccess[] = [
+        slice(EVERYONE_TEAM, await accessControl.canReadAsEveryoneBatch(wsId, probes)),
+      ];
+      for (const name of groups) {
+        const team = await accessControl.canReadAsGroupBatch(wsId, name, probes);
+        if (team === null) continue; // gone between the two reads — nothing to say
+        teams.push(slice(name, team));
+      }
+      res.json({ teams });
+    } catch (err) {
+      log.error('failed to list teams:', { err });
+      res.status(500).json({ error: 'Failed to list teams' });
+    }
+  });
+
+  return router;
+}
+
+const accessMdOf = (folder: string) => `${folder}/access.md`;
+const skillMdOf = (skillPath: string) => `${skillPath}/SKILL.md`;
+/** Under `Plugins/personal-<id>/…` — one person's space, whatever it grants. */
+const inPersonalPlugin = (repoPath: string) => {
+  const folder = pluginOfPath(repoPath);
+  return folder !== null && isPersonalPluginFolder(folder);
+};