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

package/src/service.ts

@@ -0,0 +1,207 @@
+// The `toolCatalog` service: the extension surface other plugins build on.
+//
+//   registerClassifier({ name, priority, group?(tool), categorize?(group) })
+//   annotate(match, { group?, category?, risk?, summary? })
+//   defineCategory(name, description)
+//   registerVisibilityFilter({ name, filter(agent, names) })
+//   refresh(), get(), resolve(target), stateOf(agent)
+//
+// Every register/annotate/define call returns a disposer. Extension plugins
+// should register inside an effect so unloading them undoes the registration:
+//   ctx.effect(() => ctx.toolCatalog.registerClassifier({...}))
+//
+// Hooks are plain Cordis events on the host context:
+//   tool-catalog/before-load    (serial; throw to veto)   { agent, targets, names }
+//                               also fired by the auto-load of a directly called
+//                               hidden tool, with `rescue: true` in the payload
+//   tool-catalog/after-load     (emit)                    { agent, targets, added }
+//   tool-catalog/before-unload  (serial; throw to veto)   { agent, targets }
+//   tool-catalog/after-unload   (emit)                    { agent, targets, removed }
+//   tool-catalog/before-rebuild (emit)                    { }
+//   tool-catalog/after-rebuild  (emit)                    { catalog }
+
+import { readFileSync, existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { DEFAULT_CATEGORIES } from './catalog.js'
+import type { Annotation, Classifier, Disposer, HostContext, Loader, Logger, PluginPackage, RegisteredResolver, TargetResolver, ToolMeta, VisibilityFilter } from './types.js'
+
+/** A classifier after registration (defaults filled in). */
+export interface RegisteredClassifier extends Classifier {
+  name: string
+  priority: number
+}
+
+/** A visibility filter after registration (defaults filled in). */
+export interface RegisteredFilter {
+  name: string
+  filter: VisibilityFilter['filter']
+}
+
+/** Package name of a loader specifier: "@scope/pkg/sub" -> "@scope/pkg", "pkg/sub" -> "pkg". */
+export function packageNameOf(specifier: string): string {
+  const parts = String(specifier).split('/')
+  return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0] ?? specifier
+}
+
+/** Find a package's package.json starting from a resolvable entry file. */
+function findManifest(requireFrom: NodeJS.Require, pkg: string): string | undefined {
+  try {
+    return requireFrom.resolve(`${pkg}/package.json`)
+  } catch {
+    // exports may hide package.json; walk up from the main entry instead.
+  }
+  try {
+    let dir = dirname(requireFrom.resolve(pkg))
+    while (dir !== dirname(dir)) {
+      const candidate = join(dir, 'package.json')
+      if (existsSync(candidate)) {
+        const json = JSON.parse(readFileSync(candidate, 'utf8'))
+        if (json.name === pkg) return candidate
+      }
+      dir = dirname(dir)
+    }
+  } catch {
+    // unresolvable from here
+  }
+  return undefined
+}
+
+/**
+ * Read `dsh.toolCatalog` declarations from every plugin package the host loader
+ * knows. Declaration format (package.json):
+ *
+ *   "dsh": { "toolCatalog": {
+ *     "match": "^adb_",                 // regex over tool names (optional)
+ *     "group": "adb", "category": "device",
+ *     "tools": { "adb_install": { "risk": "high", "summary": "..." } }
+ *   } }
+ *
+ * `group`/`category`/`risk`/`summary` at the top level apply to `match`;
+ * entries under `tools` apply to exact names and win over the top level.
+ */
+export function readManifestAnnotations(ctx: Pick<HostContext, 'get' | 'baseUrl'>, logger?: Logger): Annotation[] {
+  const annotations: Annotation[] = []
+  for (const { name: pkg, manifest: manifestPath } of listPluginPackages(ctx)) {
+    try {
+      const declared = JSON.parse(readFileSync(manifestPath, 'utf8'))?.dsh?.toolCatalog
+      if (!declared) continue
+      const top = pick(declared)
+      if (declared.match && Object.keys(top).length) annotations.push({ source: pkg, match: new RegExp(declared.match), meta: top })
+      for (const [name, meta] of Object.entries((declared.tools ?? {}) as Record<string, unknown>)) {
+        annotations.push({ source: pkg, match: name, meta: { ...top, ...pick(meta) } })
+      }
+    } catch (error) {
+      logger?.warn?.(`tool-manager: bad dsh.toolCatalog in ${pkg}: ${(error as Error).message}`)
+    }
+  }
+  return annotations
+}
+
+/**
+ * Every enabled plugin package the host loader knows, as
+ * `{ name, dir, manifest }`. Relative (local) entries are skipped.
+ */
+export function listPluginPackages(ctx: Pick<HostContext, 'get' | 'baseUrl'>): PluginPackage[] {
+  const loader = ctx.get?.('loader') as Loader | undefined
+  if (!loader?.entries) return []
+  const bases = [loader.baseUrl, loader.ctx?.baseUrl, ctx.baseUrl, pathToFileURL(join(process.cwd(), 'noop.js')).href].filter((b): b is string => Boolean(b))
+  const seen = new Set<string>()
+  const out: PluginPackage[] = []
+  for (const entry of loader.entries()) {
+    const spec = entry?.options?.name
+    if (typeof spec !== 'string' || spec.startsWith('.') || entry.options?.disabled === true) continue
+    const pkg = packageNameOf(spec)
+    if (seen.has(pkg)) continue
+    seen.add(pkg)
+    for (const base of bases) {
+      const from = createRequire(base.startsWith('file:') ? fileURLToPath(base) : join(base, 'noop.js'))
+      const manifest = findManifest(from, pkg)
+      if (manifest) {
+        out.push({ name: pkg, dir: dirname(manifest), manifest })
+        break
+      }
+    }
+  }
+  return out
+}
+
+const META_KEYS = ['group', 'category', 'risk', 'summary'] as const
+
+function pick(meta: unknown = {}): ToolMeta {
+  const out: ToolMeta = {}
+  if (typeof meta !== 'object' || meta === null) return out
+  for (const key of META_KEYS) {
+    const value = (meta as Record<string, unknown>)[key]
+    if (typeof value === 'string' && value) out[key] = value
+  }
+  return out
+}
+
+/** Registries behind the service. `onChange` rebuilds the catalog. */
+export function createRegistries(onChange: () => void) {
+  const classifiers = new Set<RegisteredClassifier>()
+  const annotations: Annotation[] = []
+  const categories = new Map(Object.entries(DEFAULT_CATEGORIES))
+  const filters = new Set<RegisteredFilter>()
+  const resolvers = new Set<RegisteredResolver>()
+
+  const remover = (fn: () => unknown): Disposer => {
+    let done = false
+    return () => {
+      if (done) return
+      done = true
+      fn()
+      onChange()
+    }
+  }
+
+  return {
+    classifiers,
+    annotations,
+    categories,
+    filters,
+    resolvers,
+    registerClassifier(classifier: Classifier): Disposer {
+      if (!classifier || (typeof classifier.group !== 'function' && typeof classifier.categorize !== 'function')) {
+        throw new TypeError('registerClassifier: provide group(tool) and/or categorize(group)')
+      }
+      const entry: RegisteredClassifier = { name: classifier.name ?? 'anonymous', priority: Number(classifier.priority ?? 0), group: classifier.group, categorize: classifier.categorize }
+      classifiers.add(entry)
+      onChange()
+      return remover(() => classifiers.delete(entry))
+    },
+    annotate(match: string | RegExp, meta: ToolMeta): Disposer {
+      const entry: Annotation = { source: 'runtime', match: typeof match === 'string' ? match : new RegExp(match), meta: pick(meta) }
+      annotations.push(entry)
+      onChange()
+      return remover(() => annotations.splice(annotations.indexOf(entry), 1))
+    },
+    defineCategory(name: string, description = ''): Disposer {
+      const previous = categories.get(name)
+      categories.set(name, description)
+      onChange()
+      return remover(() => (previous === undefined ? categories.delete(name) : categories.set(name, previous)))
+    },
+    registerVisibilityFilter(filter: VisibilityFilter): Disposer {
+      if (typeof filter?.filter !== 'function') throw new TypeError('registerVisibilityFilter: provide filter(agent, names)')
+      const entry = { name: filter.name ?? 'anonymous', filter: filter.filter }
+      filters.add(entry)
+      onChange()
+      return remover(() => filters.delete(entry))
+    },
+    /**
+     * Own a target prefix in tools_load / tools_ls / tools_unload. `resolve` gets
+     * the raw target and returns one or more ordinary targets (paths, group or
+     * tool names), or undefined to pass.
+     */
+    registerTargetResolver(resolver: TargetResolver): Disposer {
+      if (typeof resolver?.resolve !== 'function') throw new TypeError('registerTargetResolver: provide resolve(target)')
+      const entry = { name: resolver.name ?? 'anonymous', prefix: String(resolver.prefix ?? ''), resolve: resolver.resolve }
+      resolvers.add(entry)
+      onChange()
+      return remover(() => resolvers.delete(entry))
+    },
+  }
+}

package/src/types.ts

@@ -0,0 +1,319 @@
+// Types shared by the core modules and exported for extension plugins.
+//
+// The host surface is described structurally (only what this plugin touches)
+// instead of importing the host's Cordis types, so the package type-checks
+// without the host packages installed next to it.
+
+// --- catalog -------------------------------------------------------------------
+
+/** A tool schema as the host lists it. */
+export interface ToolSchema {
+  name: string
+  description?: string
+  parameters?: unknown
+  [key: string]: unknown
+}
+
+/** Metadata a plugin can attach to tools (package.json `dsh.toolCatalog` or annotate()). */
+export interface ToolMeta {
+  group?: string
+  category?: string
+  risk?: string
+  summary?: string
+}
+
+export interface Annotation {
+  source?: string
+  match: string | RegExp
+  meta: ToolMeta
+}
+
+export interface ToolEntry {
+  name: string
+  /** Name inside its group (MCP routing prefix dropped). */
+  short: string
+  group: string
+  /** Where the structural fallback alone would have put the tool. */
+  fallbackGroup: string
+  category: string
+  summary: string
+  description: string
+  tokens: number
+  highRisk: boolean
+  annotation: ToolMeta
+}
+
+export interface Group {
+  name: string
+  category: string
+  tools: ToolEntry[]
+}
+
+export interface Category {
+  name: string
+  description: string
+  groups: Group[]
+  /** Set on a synthetic alias node (several targets behind one name). */
+  alias?: string[]
+  /** The exact tools an alias stands for; load these, never their whole groups. */
+  aliasTools?: ToolEntry[]
+}
+
+export interface Catalog {
+  tools: Map<string, ToolEntry>
+  groups: Map<string, Group>
+  categories: Map<string, Category>
+}
+
+export type CatalogNode =
+  | { kind: 'root' }
+  | { kind: 'category', category: Category }
+  | { kind: 'group', group: Group }
+  | { kind: 'tool', tool: ToolEntry }
+  | { kind: 'missing', target: string }
+
+/** What a classifier sees of one tool. */
+export interface ToolProbe {
+  name: string
+  description: string
+  annotation: ToolMeta
+}
+
+/** What a classifier sees of one group. */
+export interface GroupProbe {
+  name: string
+  tools: ToolProbe[]
+}
+
+export interface Classifier {
+  name?: string
+  priority?: number
+  /** Group name for a tool, or undefined to pass. */
+  group?(tool: ToolProbe): string | undefined
+  /** Category for a group, or undefined to pass. */
+  categorize?(group: GroupProbe): string | undefined
+}
+
+export interface VisibilityFilter {
+  name?: string
+  /** Names to keep out of `names`; may only narrow. */
+  filter(agent: Agent, names: string[]): Iterable<string> | undefined | null
+}
+
+export interface TargetResolver {
+  name?: string
+  /** Targets starting with this prefix are offered to `resolve` first. */
+  prefix?: string
+  /** One or more ordinary targets to resolve instead, or undefined to pass. */
+  resolve(target: string): string | string[] | undefined | null
+}
+
+/** A registry entry after registration (defaults filled in). */
+export interface RegisteredResolver {
+  name: string
+  prefix: string
+  resolve: TargetResolver['resolve']
+}
+
+export type Disposer = () => void
+
+// --- per-agent state ---------------------------------------------------------
+
+export interface LoadState {
+  /** Individual tool names. */
+  loaded: Set<string>
+  /** Subscribed group names (tools the group gains later included). */
+  groups: Set<string>
+  /** Tools unloaded from inside a subscribed group. */
+  excluded: Set<string>
+  /** Groups handed to subagents started later. */
+  handoffGroups: Set<string>
+  /** Tools handed to subagents started later. */
+  handoffTools: Set<string>
+}
+
+/** Plain JSON form of a LoadState (sorted arrays). */
+export type SerializedState = { [K in keyof LoadState]: string[] }
+
+export interface StateProvider {
+  name?: string
+  /** A serialized state for the agent, or null when there is none. */
+  load?(agent: Agent): Partial<SerializedState> | null | undefined
+  save?(agent: Agent, state: SerializedState): void
+}
+
+export interface RiskGate {
+  name?: string
+}
+
+// --- host surface --------------------------------------------------------------
+
+export interface Logger {
+  debug?(message: string): void
+  info?(message: string): void
+  warn?(message: string): void
+}
+
+export interface SessionEvent {
+  type?: string
+  data?: { provider?: string, [key: string]: unknown }
+}
+
+export interface Session {
+  id?: unknown
+  seq?: number
+  eventAt?(seq: number): SessionEvent | undefined
+  requestHeader?(): { provider?: string } | undefined
+}
+
+/** An agent as this plugin uses it. */
+export interface Agent {
+  id: unknown
+  options?: { provider?: string }
+  session?: Session
+  ctx?: {
+    tools?: {
+      restrict?(spec: { allow?: string[], deny?: string[] }): Disposer
+    }
+  }
+}
+
+export interface AgentsApi {
+  list(): Agent[]
+  get?(id: unknown): Agent | undefined
+  isOwnedBy?(childId: unknown, candidate: Agent): boolean
+}
+
+/** Context a plugin receives once `agents` is injected. */
+export interface AgentContext {
+  agents: AgentsApi
+  effect(fn: () => Disposer | void, label?: string): void
+  // any: each event passes its own argument types, and a handler typed
+  // (...args: unknown[]) would reject every concretely typed listener.
+  on(event: string, handler: (...args: any[]) => unknown): Disposer
+}
+
+export interface ToolLayer {
+  tools: Map<string, { description?: string, parameters?: unknown }>
+}
+
+export interface HostTools {
+  schemas(agent?: Agent): ToolSchema[]
+  register(definition: unknown): Disposer | void
+  view?(agent: Agent): { restrictableNames: Iterable<string> }
+  schemaOf?(definition: unknown, deferred: boolean): ToolSchema
+  layers?: {
+    chainLayers?(agent: Agent): Iterable<ToolLayer>
+    peek?(agent: Agent): ToolLayer | undefined
+  }
+}
+
+export interface LoaderEntry {
+  options?: { name?: unknown, disabled?: boolean }
+}
+
+export interface Loader {
+  entries?(): Iterable<LoaderEntry>
+  baseUrl?: string
+  ctx?: { baseUrl?: string }
+}
+
+/** The host context the core plugin is applied to. */
+export interface HostContext {
+  tools: HostTools
+  logger?: ((name: string) => Logger) | Logger
+  baseUrl?: string
+  get?(name: string): unknown
+  emit(event: string, ...args: unknown[]): void
+  serial(event: string, ...args: unknown[]): Promise<unknown>
+  // any: each event passes its own argument types, and a handler typed
+  // (...args: unknown[]) would reject every concretely typed listener.
+  on(event: string, handler: (...args: any[]) => unknown): Disposer
+  effect(fn: () => Disposer | void, label?: string): void
+  inject?(deps: string[], fn: (ctx: AgentContext) => void): void
+  provide(name: string, service: unknown): void
+}
+
+/** Configuration of the core plugin. */
+export interface CoreConfig {
+  /** Extra always-on tools. */
+  pinned?: string[]
+  /** Tools removed from the default always-on list. */
+  unpin?: string[]
+  /** Tool names treated as high risk. */
+  highRisk?: string[]
+  /** Model routes never narrowed (default ["claude-code"]). */
+  exemptProviders?: string[]
+}
+
+/** A plugin package the host loader knows. */
+export interface PluginPackage {
+  name: string
+  dir: string
+  manifest: string
+}
+
+// --- the toolCatalog service -----------------------------------------------------
+
+/** A search hit from toolCatalog.find(). */
+export interface FoundTool {
+  name: string
+  short: string
+  path: string
+  category: string
+  group: string
+  summary: string
+  tokens: number
+  highRisk: boolean
+}
+
+/** The service the core provides as `toolCatalog` (inject it to extend the catalog). */
+export interface ToolCatalogService {
+  registerClassifier(classifier: Classifier): Disposer
+  annotate(match: string | RegExp, meta: ToolMeta): Disposer
+  defineCategory(name: string, description?: string): Disposer
+  registerVisibilityFilter(filter: VisibilityFilter): Disposer
+  /** Own a target prefix (`"cap:"`) in tools_load / tools_ls / tools_unload. */
+  registerTargetResolver(resolver: TargetResolver): Disposer
+  /** Let loaded state outlive the process (see dsh-tool-manager-persist). */
+  registerStateProvider(provider?: StateProvider): Disposer
+  /** Declare that a plugin confirms high-risk loads; without one they are refused. */
+  registerRiskGate(gate?: RiskGate): Disposer
+  riskGates(): string[]
+  /** Re-read package declarations and rebuild. */
+  refresh(): void
+  /** Catalog as one agent sees it, or the union over live agents. */
+  get(agent?: Agent): Catalog
+  resolve(target: string, agent?: Agent): CatalogNode
+  stateOf(agent: Agent): LoadState
+  exportState(agent: Agent): SerializedState
+  importState(agent: Agent, state: Partial<SerializedState>): void
+  /** Names visible to the agent, or null when this plugin does not restrict it. */
+  allowFor(agent: Agent): string[] | null
+  /** True when the agent's model route is in `exemptProviders` (never narrowed). */
+  isExempt(agent: Agent): boolean
+  /** Load through the same path as tools_load; returns the model-facing text. */
+  load(agent: Agent, targets: readonly string[], options?: { forSubagents?: boolean }): Promise<string>
+  unload(agent: Agent, targets: readonly string[]): Promise<string>
+  /** Live agents, each with its parent when it is a subagent. */
+  agents(): { agent: Agent, id: string, parentId: string | null }[]
+  config(): { pinned: string[], entryTools: string[], extraPinned: string[], unpinned: string[], highRisk: string[] }
+  packages(): PluginPackage[]
+  extensions(): {
+    classifiers: { name: string, priority: number }[]
+    filters: string[]
+    annotations: { source: string | undefined, match: string }[]
+    categories: string[]
+    riskGates: string[]
+    stateProviders: string[]
+  }
+  /** Structured cross-directory search (same matching as tools_ls with a query). */
+  find(query: string, path?: string): FoundTool[]
+  /** Schema tokens actually sent for an agent: pinned tools plus its loaded set. */
+  wireTokens(agent: Agent): number
+}
+
+/** What an extension plugin uses of its context after `inject: ['toolCatalog']`. */
+export interface ExtensionContext extends Pick<HostContext, 'logger' | 'effect' | 'on'> {
+  toolCatalog: ToolCatalogService
+}