@lvy-jsd/dsh-tool-manager 0.0.0-stage → 0.4.0

package/src/catalog.ts

@@ -0,0 +1,305 @@
+// Builds the three-level tool directory: category -> group -> tool.
+//
+// The core knows no rules. Placement comes from, in order:
+//   1. override classifiers (priority >= OVERRIDE_PRIORITY), e.g. user config
+//   2. annotations declared by plugins (package.json `dsh.toolCatalog`, annotate())
+//   3. ordinary classifiers, highest priority first
+//   4. a structural fallback: group from the tool name, category `uncategorized`
+//
+// Grouping never decides visibility; a misplaced tool is only listed in the
+// wrong place, never lost.
+
+import type { Annotation, Catalog, CatalogNode, Category, Classifier, Group, GroupProbe, RegisteredResolver, ToolEntry, ToolMeta, ToolProbe, ToolSchema } from './types.js'
+
+export const UNCATEGORIZED = 'uncategorized'
+export const MISC_GROUP = 'misc'
+export const OVERRIDE_PRIORITY = 1000
+
+// The fixed category vocabulary. Plugins may add more with defineCategory().
+export const DEFAULT_CATEGORIES: Record<string, string> = {
+  device: 'Phones, Android, ADB and desktop control',
+  code: 'Source hosting, repositories and package tooling',
+  media: 'Video, image and audio services',
+  maps: 'Maps, geocoding and routing',
+  browser: 'Headless browser automation',
+  memory: 'Long-term memory and knowledge stores',
+  collaboration: 'Bots, group chats, teammates and other sessions',
+  automation: 'Schedules and automated runs',
+  connectors: 'MCP connector administration',
+  search: 'Web and social search',
+  system: 'Host, OS and secrets',
+  [UNCATEGORIZED]: 'Tools no classifier has placed yet',
+}
+
+// Leading words that describe an action rather than an owner; a shared verb
+// prefix ("list_", "get_") is not a meaningful group.
+const VERB_PREFIXES = new Set([
+  'add', 'ask', 'attach', 'create', 'delete', 'detach', 'edit', 'exit', 'get',
+  'interrupt', 'list', 'message', 'open', 'post', 'read', 'remove', 'request',
+  'run', 'save', 'send', 'set', 'spawn', 'stop', 'update', 'wait', 'write',
+])
+
+/**
+ * Structural group for a tool name, used when nothing else places it:
+ * `mcp__server__tool` -> server, `mcp__server__sub__tool` -> server-sub,
+ * `prefix_rest` -> prefix when at least two tools share a non-verb prefix, else misc.
+ */
+export function structuralGroup(name: string, prefixCounts: Map<string, number>): string {
+  if (name.startsWith('mcp__')) {
+    const parts = name.slice(5).split('__')
+    if (parts.length >= 3) return `${parts[0]}-${parts[1]}`
+    return parts[0]
+  }
+  const prefix = name.split('_')[0]
+  if (prefix !== name && !VERB_PREFIXES.has(prefix) && (prefixCounts.get(prefix) ?? 0) >= 2) return prefix
+  return MISC_GROUP
+}
+
+/** Short form of a tool name inside its group (drops the MCP routing prefix). */
+export function shortName(name: string): string {
+  if (!name.startsWith('mcp__')) return name
+  const parts = name.slice(5).split('__')
+  return parts[parts.length - 1] ?? name
+}
+
+/** First sentence of a description, capped for one-line listings. */
+export function summary(text: string | undefined, max = 80): string {
+  const flat = String(text ?? '').replace(/\s+/g, ' ').trim()
+  const first = flat.split(/(?<=[.!?。！？])\s/)[0] ?? ''
+  return first.length > max ? `${first.slice(0, max - 1)}…` : first
+}
+
+/** Rough token cost of one schema as the model receives it. */
+export function estimateTokens(schema: unknown): number {
+  const text = JSON.stringify(schema)
+  // CJK and other wide characters cost roughly one token each, not a quarter.
+  let wide = 0
+  for (const ch of text) if ((ch.codePointAt(0) ?? 0) > 0x2e7f) wide += 1
+  return Math.ceil((text.length - wide) / 4 + wide)
+}
+
+/** Merge every annotation that applies to `name`; later annotations win per field. */
+function annotationFor(name: string, annotations: readonly Annotation[]): ToolMeta {
+  let merged: ToolMeta | undefined
+  for (const a of annotations) {
+    const hit = typeof a.match === 'string' ? a.match === name : a.match.test(name)
+    if (hit) merged = { ...merged, ...a.meta }
+  }
+  return merged ?? {}
+}
+
+/**
+ * A group a classifier renamed (e.g. attribution-scan: `phone` -> `phone-control`)
+ * is unknown to category rules written for the old name. Ask the classifiers
+ * about the structural groups its tools came from instead; the category covering
+ * the most tools wins.
+ */
+function inheritedCategory(group: Group, classifiers: readonly Classifier[]): string | undefined {
+  const byFallback = new Map<string, ToolEntry[]>()
+  for (const tool of group.tools) {
+    if (tool.fallbackGroup === group.name) continue
+    let list = byFallback.get(tool.fallbackGroup)
+    if (!list) byFallback.set(tool.fallbackGroup, (list = []))
+    list.push(tool)
+  }
+  const votes = new Map<string, number>()
+  for (const [name, tools] of byFallback) {
+    const probe: GroupProbe = { name, tools: tools.map(({ name: n, description, annotation }) => ({ name: n, description, annotation })) }
+    const category = firstResult(classifiers, 'categorize', probe)
+    if (category && category !== UNCATEGORIZED) votes.set(category, (votes.get(category) ?? 0) + tools.length)
+  }
+  let best: [string, number] | undefined
+  for (const [category, count] of votes) if (!best || count > best[1]) best = [category, count]
+  return best?.[0]
+}
+
+function firstResult(classifiers: readonly Classifier[], method: 'group', arg: ToolProbe): string | undefined
+function firstResult(classifiers: readonly Classifier[], method: 'categorize', arg: GroupProbe): string | undefined
+function firstResult(classifiers: readonly Classifier[], method: 'group' | 'categorize', arg: ToolProbe | GroupProbe): string | undefined {
+  for (const c of classifiers) {
+    const fn = c[method] as ((arg: ToolProbe | GroupProbe) => unknown) | undefined
+    if (typeof fn !== 'function') continue
+    try {
+      const value = fn.call(c, arg)
+      if (typeof value === 'string' && value) return value
+    } catch {
+      // A failing classifier is skipped, never fatal.
+    }
+  }
+  return undefined
+}
+
+export interface BuildOptions {
+  /** Placement rules; priority >= OVERRIDE_PRIORITY beats plugin declarations. */
+  classifiers?: readonly Classifier[]
+  annotations?: readonly Annotation[]
+  /** Category vocabulary (name -> description). */
+  categories?: Record<string, string>
+  /** Tool names configured as high risk. */
+  highRisk?: readonly string[]
+}
+
+/**
+ * Build the directory index.
+ * @param schemas - catalog tools (pinned already removed)
+ */
+export function buildCatalog(schemas: readonly ToolSchema[], { classifiers = [], annotations = [], categories = DEFAULT_CATEGORIES, highRisk = [] }: BuildOptions = {}): Catalog {
+  const sorted = [...classifiers].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0))
+  const overrides = sorted.filter((c) => (c.priority ?? 0) >= OVERRIDE_PRIORITY)
+  const ordinary = sorted.filter((c) => (c.priority ?? 0) < OVERRIDE_PRIORITY)
+
+  const prefixCounts = new Map<string, number>()
+  for (const { name } of schemas) {
+    const prefix = name.split('_')[0]
+    if (prefix !== name) prefixCounts.set(prefix, (prefixCounts.get(prefix) ?? 0) + 1)
+  }
+
+  const risky = new Set(highRisk)
+  const tools = new Map<string, ToolEntry>()
+  const groups = new Map<string, Group>()
+  for (const schema of schemas) {
+    const meta = annotationFor(schema.name, annotations)
+    const probe: ToolProbe = { name: schema.name, description: schema.description ?? '', annotation: meta }
+    const group = firstResult(overrides, 'group', probe)
+      ?? meta.group
+      ?? firstResult(ordinary, 'group', probe)
+      ?? structuralGroup(schema.name, prefixCounts)
+    const entry: ToolEntry = {
+      name: schema.name,
+      short: shortName(schema.name),
+      group,
+      // Where the structural fallback alone would have put it; a renamed group
+      // inherits that group's category (see below).
+      fallbackGroup: structuralGroup(schema.name, prefixCounts),
+      category: UNCATEGORIZED,
+      summary: meta.summary ? summary(meta.summary) : summary(schema.description),
+      description: schema.description ?? '',
+      tokens: estimateTokens(schema),
+      highRisk: risky.has(schema.name) || meta.risk === 'high',
+      annotation: meta,
+    }
+    tools.set(schema.name, entry)
+    let bucket = groups.get(group)
+    if (!bucket) groups.set(group, (bucket = { name: group, category: UNCATEGORIZED, tools: [] }))
+    bucket.tools.push(entry)
+  }
+
+  for (const group of groups.values()) {
+    group.tools.sort((a, b) => a.short.localeCompare(b.short))
+    const probe: GroupProbe = { name: group.name, tools: group.tools.map(({ name, description, annotation }) => ({ name, description, annotation })) }
+    const annotated = group.tools.map((t) => t.annotation.category).find(Boolean)
+    group.category = firstResult(overrides, 'categorize', probe)
+      ?? annotated
+      ?? firstResult(ordinary, 'categorize', probe)
+      ?? inheritedCategory(group, [...overrides, ...ordinary])
+      ?? UNCATEGORIZED
+    for (const tool of group.tools) tool.category = group.category
+  }
+
+  const categoryIndex = new Map<string, Category>()
+  for (const [name, description] of Object.entries(categories)) categoryIndex.set(name, { name, description, groups: [] })
+  for (const group of groups.values()) {
+    let category = categoryIndex.get(group.category)
+    if (!category) categoryIndex.set(group.category, (category = { name: group.category, description: '', groups: [] }))
+    category.groups.push(group)
+  }
+  for (const category of categoryIndex.values()) category.groups.sort((a, b) => a.name.localeCompare(b.name))
+
+  return { tools, groups, categories: categoryIndex }
+}
+
+/**
+ * Resolve a target into catalog nodes.
+ * Accepts "/", "/category", "/category/group", "/category/group/tool",
+ * a bare category or group name, a full tool name, or a unique short tool name.
+ */
+/**
+ * Resolve a target string to a node.
+ *
+ * `resolvers` lets a plugin own a prefix (`cap:`, say): each is consulted before
+ * the built-in rules and returns a list of target strings to resolve instead, or
+ * undefined to pass. A plugin can therefore add a target vocabulary without the
+ * core knowing anything about it.
+ */
+// Path segments are lowercased, but names keep their original case (an MCP
+// server called "GitHub"), so lookups must not depend on it. The names stay as
+// they are because persisted state stores them.
+const findCI = <T extends { name: string }>(map: Map<string, T>, key: string): T | undefined =>
+  map.get(key) ?? [...map.values()].find((v) => v.name.toLowerCase() === key)
+
+export function resolveTarget(catalog: Catalog, raw: unknown, resolvers: readonly Pick<RegisteredResolver, 'prefix' | 'resolve'>[] = []): CatalogNode {
+  const target = String(raw ?? '').trim()
+  for (const { prefix, resolve } of resolvers) {
+    if (prefix && !target.startsWith(prefix)) continue
+    let expanded: string | string[] | undefined | null
+    try {
+      expanded = resolve(target)
+    } catch {
+      continue
+    }
+    if (expanded === undefined || expanded === null) continue
+    const list = Array.isArray(expanded) ? expanded : [expanded]
+    const nodes = list.map((one) => resolveTarget(catalog, one, resolvers))
+    if (nodes.length === 0) return { kind: 'missing', target }
+    if (nodes.length === 1) return nodes[0]!
+    // Several targets behind one alias: expose them as a synthetic category so
+    // loading, listing and unloading all work through the existing paths.
+    const tools = nodes.flatMap((node) => toolsUnder(catalog, node))
+    // `aliasTools` is the exact tool list. The node's groups are copies, so
+    // loading must use this list rather than subscribe to the group names —
+    // otherwise a shared group would drag in every sibling tool.
+    return {
+      kind: 'category',
+      category: { name: target, description: `Alias for ${list.join(', ')}`, groups: groupsOf(tools), alias: list, aliasTools: tools },
+    }
+  }
+  if (target === '' || target === '/') return { kind: 'root' }
+  const exact = catalog.tools.get(target)
+  if (exact) return { kind: 'tool', tool: exact }
+  const parts = target.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean).map((p) => p.toLowerCase())
+  if (parts.length === 1) {
+    const only = parts[0]!
+    const category = findCI(catalog.categories, only)
+    if (category) return { kind: 'category', category }
+    const group = findCI(catalog.groups, only)
+    if (group) return { kind: 'group', group }
+    const byShort = [...catalog.tools.values()].filter((t) => t.short.toLowerCase() === only)
+    if (byShort.length === 1) return { kind: 'tool', tool: byShort[0]! }
+    return { kind: 'missing', target }
+  }
+  const [cat = '', grp, tool] = parts
+  const category = findCI(catalog.categories, cat)
+  if (!category) return { kind: 'missing', target }
+  const group = category.groups.find((g) => g.name.toLowerCase() === grp)
+  if (!group) return { kind: 'missing', target }
+  if (parts.length === 2) return { kind: 'group', group }
+  const entry = group.tools.find((t) => t.short.toLowerCase() === tool || t.name.toLowerCase() === tool)
+  if (!entry || parts.length > 3) return { kind: 'missing', target }
+  return { kind: 'tool', tool: entry }
+}
+
+/**
+ * Regroup an exact tool list by its original group, for synthetic nodes.
+ *
+ * The groups are copies holding only the given tools: reusing the catalog's own
+ * group objects would drag in every sibling tool, so an alias would load far
+ * more than it declares.
+ */
+function groupsOf(tools: readonly ToolEntry[]): Group[] {
+  const byName = new Map<string, Group>()
+  for (const tool of tools) {
+    let group = byName.get(tool.group)
+    if (!group) byName.set(tool.group, (group = { name: tool.group, category: tool.category, tools: [] }))
+    if (!group.tools.includes(tool)) group.tools.push(tool)
+  }
+  return [...byName.values()]
+}
+
+/** Tools under a node (whole tree for root). */
+export function toolsUnder(catalog: Catalog, node: CatalogNode): ToolEntry[] {
+  if (node.kind === 'root') return [...catalog.tools.values()]
+  if (node.kind === 'category') return node.category.groups.flatMap((g) => g.tools)
+  if (node.kind === 'group') return node.group.tools
+  if (node.kind === 'tool') return [node.tool]
+  return []
+}

package/src/exempt.ts

@@ -0,0 +1,148 @@
+// File-based exemption list for dsh-tool-manager.
+//
+// An exempt session is never narrowed: a route whose tool list is handed to an
+// external client once at session start (Claude Code, say) cannot load a tool
+// that was hidden from the first request, so hiding anything there only loses
+// tools. The provider list originally came from `exemptProviders` in
+// cordis.patch.yml, which a user cannot edit from the browser and which is
+// awkward to change per session.
+//
+// This file replaces it: when <DSH_HOME>/tool-manager/exempt.json exists it wins
+// over the plugin config, the same way the settings file does. Two entry forms
+// are supported, because they answer different questions:
+//
+//   { "providers": ["claude-code"], "sessions": ["s_abc123"] }
+//
+//   providers  model routes never narrowed, for every session (durable)
+//   sessions   one session exempted for its remaining lifetime, e.g. while the
+//              user checks whether a client handles lazy loading (temporary)
+//
+// Sessions are matched against the agent's session id and, as a fallback, the
+// agent id, so an entry can be removed by hand without knowing which of the two
+// the host populated.
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import type { Logger } from './types.js'
+
+/** An exemption list: routes and sessions. Both may be empty. */
+export interface ExemptConfig {
+  providers: string[]
+  sessions: string[]
+}
+
+/** Where the exemption file lives unless a deployment points elsewhere. */
+export function defaultExemptFile(): string {
+  const dshHome = process.env.DSH_HOME || join(homedir(), '.config', 'deepseek-harness')
+  return join(dshHome, 'tool-manager', 'exempt.json')
+}
+
+/** Keep only non-empty strings; a number or object in the file is a typo, not a name. */
+function pickNames(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  return value.filter((name): name is string => typeof name === 'string' && name.trim().length > 0).map((name) => name.trim())
+}
+
+/** The whole file, with unknown keys dropped. */
+export function pickExempt(raw: unknown): ExemptConfig {
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return { providers: [], sessions: [] }
+  const record = raw as Record<string, unknown>
+  // `providers` is required: a file that omits it says "no route is exempt",
+  // not "keep the old config list", because the file is the override.
+  return { providers: pickNames(record.providers), sessions: pickNames(record.sessions) }
+}
+
+/** Read the exemption file; missing or corrupt is "no opinion", never a crash. */
+export function readExemptFile(file: string, logger?: Logger): ExemptConfig | undefined {
+  let text: string
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch (caught) {
+    const error = caught as NodeJS.ErrnoException
+    // ENOENT is the normal first run: no file means the plugin config decides.
+    if (error.code !== 'ENOENT') logger?.warn?.(`tool-manager: ignoring unreadable exemptions ${file}: ${error.message}`)
+    return undefined
+  }
+  try {
+    return pickExempt(JSON.parse(text))
+  } catch (caught) {
+    // A corrupt file must not silently restore the config list: the user
+    // intended the file to be in charge, so report and treat it as "no exempt".
+    logger?.warn?.(`tool-manager: unreadable exemptions ${file}: ${(caught as Error).message}`)
+    return { providers: [], sessions: [] }
+  }
+}
+
+/** Write the file atomically, so a crash cannot leave a half-written list. */
+export function writeExemptFile(file: string, config: ExemptConfig, logger?: Logger): void {
+  mkdirSync(dirname(file), { recursive: true })
+  const tmp = `${file}.tmp`
+  try {
+    writeFileSync(tmp, `${JSON.stringify({ providers: config.providers, sessions: config.sessions }, null, 2)}\n`)
+    renameSync(tmp, file)
+  } catch (caught) {
+    logger?.warn?.(`tool-manager: writing exemptions ${file} failed: ${(caught as Error).message}`)
+    throw caught
+  }
+}
+
+/** Why a session is exempt, for the panel to show. */
+export interface ExemptReason {
+  exempt: boolean
+  /** 'file:provider' | 'file:session' | 'config:provider' | '' */
+  source: string
+}
+
+export interface ExemptStore {
+  /** File the store reads and writes; the file itself is the override switch. */
+  file: string
+  /** True when the file exists, so the config provider list is ignored. */
+  present(): boolean
+  /** The lists in force: the file when it exists, else the plugin config. */
+  effective(): ExemptConfig
+  /** Why one session is exempt, if it is. */
+  reasonFor(provider: string | undefined, sessionId: string | undefined): ExemptReason
+  /** Add or remove one session, writing the file. Returns the lists in force. */
+  setSession(sessionId: string, exempt: boolean): ExemptConfig
+  /** Re-read the file, for after an external edit. Returns the lists in force. */
+  reload(): ExemptConfig
+}
+
+/**
+ * Exemption store over one file, with the plugin config as the fallback layer.
+ * The file wins as a whole rather than per key: an operator writing the file
+ * means it, and a partial merge would leave entries they cannot see.
+ */
+export function createExemptStore({ file, configProviders = [], logger }: { file: string, configProviders?: readonly string[], logger?: Logger }): ExemptStore {
+  let fromFile = readExemptFile(file, logger)
+  const effective = (): ExemptConfig => fromFile ?? { providers: [...configProviders], sessions: [] }
+  return {
+    file,
+    present: () => fromFile !== undefined,
+    effective,
+    reasonFor(provider, sessionId) {
+      const current = effective()
+      if (provider !== undefined && current.providers.includes(provider)) {
+        return { exempt: true, source: fromFile !== undefined ? 'file:provider' : 'config:provider' }
+      }
+      if (sessionId !== undefined && current.sessions.includes(sessionId)) return { exempt: true, source: 'file:session' }
+      return { exempt: false, source: '' }
+    },
+    setSession(sessionId, exempt) {
+      // Editing starts from what is in force, so the first panel click writes a
+      // file that keeps the exemptions the user could already see.
+      const current = effective()
+      const sessions = new Set(current.sessions)
+      if (exempt) sessions.add(sessionId)
+      else sessions.delete(sessionId)
+      fromFile = { providers: [...current.providers], sessions: [...sessions] }
+      writeExemptFile(file, fromFile, logger)
+      return effective()
+    },
+    reload() {
+      fromFile = readExemptFile(file, logger)
+      return effective()
+    },
+  }
+}