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

package/src/router/types.ts

@@ -0,0 +1,149 @@
+// Types shared by the tool-router modules.
+//
+// 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.
+
+export type Disposer = () => void
+
+export interface Logger {
+  info?(...args: unknown[]): void
+  warn?(...args: unknown[]): void
+  debug?(...args: unknown[]): void
+  error?(...args: unknown[]): void
+}
+
+/** A tool schema as the host lists it (fallback mode, no toolCatalog). */
+export interface ToolSchema {
+  name: string
+  description?: string
+  [key: string]: unknown
+}
+
+/** A ref into the tool index, aligned to the index doc id. */
+export interface ToolRef {
+  name: string
+  path: string
+  summary: string
+  description: string
+  group: string
+  category: string
+  tokens: number
+  highRisk: boolean
+}
+
+/** A ref into the skill index, aligned to the index doc id. */
+export interface SkillRef {
+  name: string
+  summary: string
+  whenToUse: string
+  source?: string
+  provider?: string
+}
+
+/** A ranked hit: a ref plus its BM25 score. */
+export interface Hit<T> {
+  ref: T
+  score: number
+}
+
+/** One tool entry as the toolCatalog service lists it. */
+export interface CatalogToolEntry {
+  name: string
+  short: string
+  group: string
+  category: string
+  summary: string
+  description: string
+  tokens: number
+  highRisk?: boolean
+}
+
+/** The toolCatalog service surface this plugin uses. */
+export interface ToolCatalogService {
+  get(): { tools: Map<string, CatalogToolEntry> }
+  load(agent: unknown, targets: string[]): Promise<string>
+  wireTokens?(agent: unknown): number
+}
+
+/** One message from the llm stream. */
+export interface LlmChunk {
+  type: string
+  text?: string
+}
+
+/** The llm service surface this plugin uses. */
+export interface LlmService {
+  stream(options: {
+    provider: string
+    model: string
+    system?: string
+    messages: { role: string; content: { type: string; text: string }[] }[]
+    maxTokens?: number
+    temperature?: number
+  }): AsyncIterable<LlmChunk>
+}
+
+/** One skill as the skills service lists it. */
+export interface SkillEntry {
+  name: string
+  description?: string
+  whenToUse?: string
+  source?: string
+  provider?: string
+  invocation?: { modelInvocable?: boolean }
+}
+
+/** The skills service surface this plugin uses. */
+export interface SkillsService {
+  list(opts?: { cwd?: string; scope?: string }): Promise<SkillEntry[]>
+  get(name: string, opts?: { cwd?: string }): Promise<{ content?: string } | undefined>
+}
+
+/** A tool definition built by hand (no @deepseek-ai/dsh-tools dependency). */
+export interface ToolDef {
+  name: string
+  description: string
+  parameters: {
+    type: 'object'
+    properties: Record<string, { type: string; description: string }>
+    required: string[]
+    additionalProperties: boolean
+  }
+  output: {
+    schema: { type: 'string' }
+    render(args: unknown, value: unknown): { type: 'text'; text: string }[]
+  }
+  execute(args: Record<string, unknown>, exec?: { agent?: unknown }): Promise<string>
+  isConcurrencySafe?: () => boolean
+}
+
+/** The host context this plugin receives in apply(). */
+export interface HostContext {
+  tools: {
+    schemas(): ToolSchema[]
+    register(tool: ToolDef): void
+  }
+  toolCatalog?: ToolCatalogService
+  logger?: ((name: string) => Logger) | Logger
+  get?(name: string): unknown
+  on(event: string, handler: (...args: any[]) => unknown): Disposer
+  effect(fn: () => Disposer | void, label?: string): void
+}
+
+/** Configuration of the tool-router plugin. */
+export interface RouterConfig {
+  /** Model used to re-rank tools_route candidates. */
+  model?: { provider?: string; model?: string }
+  /** Max tokens for the re-rank call. */
+  maxTokens?: number
+  /** Default number of results. */
+  topK?: number
+  /** Token budget for loaded tool schemas. */
+  maxBudget?: number
+  /** BM25 parameters (JS fallback). */
+  k1?: number
+  b?: number
+  /** Sidecar overrides. */
+  sidecar?: { bin?: string; socket?: string; timeoutMs?: number }
+}

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/settings.ts

@@ -0,0 +1,108 @@
+// Persisted settings for dsh-tool-manager.
+//
+// The panel (and any other UI) edits these instead of `cordis.patch.yml`, which
+// a user cannot reach from the browser. The file lives beside the other state
+// in <DSH_HOME>/tool-manager/config.json, so backing up or wiping that one
+// directory covers everything this plugin persists.
+//
+// Priority: the file wins per key, the plugin config fills the keys it omits.
+// A key present in the file as an empty array therefore clears the config value
+// — that is how a UI removes an entry for good.
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import type { Logger, ToolManagerSettings } from './types.js'
+
+const KEYS = ['pinned', 'unpin', 'highRisk'] as const
+
+/** Where the panel writes settings unless a deployment points elsewhere. */
+export function defaultSettingsFile(): string {
+  const dshHome = process.env.DSH_HOME || join(homedir(), '.config', 'deepseek-harness')
+  return join(dshHome, 'tool-manager', 'config.json')
+}
+
+/**
+ * Keep only known keys holding arrays of non-empty strings. Unknown keys and
+ * wrong types are dropped rather than trusted: the file may have been hand
+ * edited, and a bad value must not reach the catalog.
+ */
+export function pickSettings(raw: unknown): ToolManagerSettings {
+  const out: ToolManagerSettings = {}
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return out
+  for (const key of KEYS) {
+    const value = (raw as Record<string, unknown>)[key]
+    // Non-string entries are dropped, not coerced: a number is a typo, not a name.
+    if (Array.isArray(value)) out[key] = value.filter((name): name is string => typeof name === 'string' && name.length > 0)
+  }
+  return out
+}
+
+/** Read the settings file; missing or corrupt is "no override", never a crash. */
+export function readSettingsFile(file: string, logger?: Logger): ToolManagerSettings {
+  try {
+    return pickSettings(JSON.parse(readFileSync(file, 'utf8')))
+  } catch (caught) {
+    const error = caught as NodeJS.ErrnoException
+    // ENOENT is the normal first run: no file means "use the plugin config".
+    if (error.code !== 'ENOENT') logger?.warn?.(`tool-manager: ignoring unreadable settings ${file}: ${error.message}`)
+    return {}
+  }
+}
+
+/** Write the file atomically, so a crash cannot leave a half-written override. */
+export function writeSettingsFile(file: string, settings: ToolManagerSettings, logger?: Logger): void {
+  mkdirSync(dirname(file), { recursive: true })
+  const tmp = `${file}.tmp`
+  try {
+    writeFileSync(tmp, `${JSON.stringify(settings, null, 2)}\n`)
+    renameSync(tmp, file)
+  } catch (caught) {
+    // Callers report the failure to the UI, so let it through after logging.
+    logger?.warn?.(`tool-manager: writing settings ${file} failed: ${(caught as Error).message}`)
+    throw caught
+  }
+}
+
+export interface SettingsStore {
+  /** File the store reads and writes. */
+  file: string
+  /** Values read from the file, before the config fallback fills gaps. */
+  stored(): ToolManagerSettings
+  /** Effective values: the file wins per key, the config fills the rest. */
+  effective(): Required<ToolManagerSettings>
+  /** Merge a patch, persist it, and return the new effective values. */
+  update(patch: ToolManagerSettings): Required<ToolManagerSettings>
+  /** Re-read the file, for after an external edit. */
+  reload(): Required<ToolManagerSettings>
+}
+
+/** Settings store over one file, with the plugin config as the fallback layer. */
+export function createSettingsStore({ file, base, logger }: { file: string, base?: ToolManagerSettings, logger?: Logger }): SettingsStore {
+  const fallback: Required<ToolManagerSettings> = {
+    pinned: base?.pinned ?? [],
+    unpin: base?.unpin ?? [],
+    highRisk: base?.highRisk ?? [],
+  }
+  let stored = readSettingsFile(file, logger)
+  const effective = (): Required<ToolManagerSettings> => ({
+    pinned: stored.pinned ?? fallback.pinned,
+    unpin: stored.unpin ?? fallback.unpin,
+    highRisk: stored.highRisk ?? fallback.highRisk,
+  })
+  return {
+    file,
+    stored: () => ({ ...stored }),
+    effective,
+    update(patch) {
+      // Merged, not replaced: a UI saving one list must not drop the others.
+      stored = { ...stored, ...pickSettings(patch) }
+      writeSettingsFile(file, stored, logger)
+      return effective()
+    },
+    reload() {
+      stored = readSettingsFile(file, logger)
+      return effective()
+    },
+  }
+}