@lvy-jsd/dsh-tool-manager 0.2.0 → 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/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()
+    },
+  }
+}

package/src/types.ts

@@ -200,7 +200,8 @@ export interface ToolLayer {
 export interface HostTools {
   schemas(agent?: Agent): ToolSchema[]
   register(definition: unknown): Disposer | void
-  view?(agent: Agent): { restrictableNames: Iterable<string> }
+  /** `visible` is what the agent ends up with after every layer's restrictions. */
+  view?(agent: Agent): { restrictableNames: Iterable<string>, visible?: { has(name: string): boolean } }
   schemaOf?(definition: unknown, deferred: boolean): ToolSchema
   layers?: {
     chainLayers?(agent: Agent): Iterable<ToolLayer>
@@ -234,6 +235,19 @@ export interface HostContext {
   provide(name: string, service: unknown): void
 }
 
+/**
+ * Settings a UI may edit at runtime. Each key is an independent list, so two
+ * writers editing different keys cannot clobber each other.
+ */
+export interface ToolManagerSettings {
+  /** Extra always-on tools. */
+  pinned?: string[]
+  /** Tools removed from the default always-on list. */
+  unpin?: string[]
+  /** Tool names treated as high risk. */
+  highRisk?: string[]
+}
+
 /** Configuration of the core plugin. */
 export interface CoreConfig {
   /** Extra always-on tools. */
@@ -244,6 +258,43 @@ export interface CoreConfig {
   highRisk?: string[]
   /** Model routes never narrowed (default ["claude-code"]). */
   exemptProviders?: string[]
+  /**
+   * Where UI-edited settings are persisted (default
+   * <DSH_HOME>/tool-manager/config.json). Those values win over the fields
+   * above, per key.
+   */
+  settingsFile?: string
+  /**
+   * Where UI-edited tool metadata is persisted (default
+   * <DSH_HOME>/tool-manager/metadata.json).
+   */
+  metadataFile?: string
+  /**
+   * Where the plain-text tool manifest is written (default
+   * ~/.claude/dsh-tool-catalog.md). Set to '' to turn it off.
+   */
+  manifestFile?: string
+  /**
+   * Where the exemption list is read from (default
+   * <DSH_HOME>/tool-manager/exempt.json). When the file exists its `providers`
+   * and `sessions` win over `exemptProviders` above; when it does not, the
+   * config list is used.
+   */
+  exemptFile?: string
+  // --- retrieval + routing (tools_find / tools_route / skills_find / skills_route) ---
+  /** Model used to re-rank tools_route / skills_route candidates. */
+  model?: { provider?: string; model?: string }
+  /** Max tokens for the re-rank call. */
+  maxTokens?: number
+  /** Default number of results for the find/route tools. */
+  topK?: number
+  /** Token budget for loaded tool schemas, reported by tools_route. */
+  maxBudget?: number
+  /** BM25 parameters (JS fallback index). */
+  k1?: number
+  b?: number
+  /** Rust sidecar overrides. */
+  sidecar?: { bin?: string; socket?: string; timeoutMs?: number }
 }
 
 /** A plugin package the host loader knows. */
@@ -290,14 +341,94 @@ export interface ToolCatalogService {
   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). */
+  /**
+   * Names this plugin lets the agent see (pinned or loaded) that another layer
+   * still hides: an MCP connector governance `deny` rule, the connector's
+   * per-session injection, or any other plugin's `restrict()`. Empty when the
+   * host cannot report the agent's final view.
+   */
+  deniedFor(agent: Agent): string[]
+  /** True when the agent is never narrowed, by route or by its session id. */
   isExempt(agent: Agent): boolean
+  /**
+   * Why the agent is exempt, so the UI can tell a route-wide exemption from one
+   * session: { exempt, source } with source 'file:provider' | 'file:session' |
+   * 'config:provider' | ''.
+   */
+  exemptionOf(agent: Agent): { exempt: boolean, source: string }
   /** 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[] }
+  /** Effective configuration, for UI display. */
+  config(): {
+    pinned: string[]
+    entryTools: string[]
+    extraPinned: string[]
+    unpinned: string[]
+    highRisk: string[]
+    exemptProviders: string[]
+    /** Session ids exempted for their own lifetime by the exemption file. */
+    exemptSessions: string[]
+    defaults: string[]
+    /** Where UI edits are persisted. */
+    settingsFile: string
+    /** True when a settings file exists and overrides the plugin config. */
+    hasSettings: boolean
+    /** Where the exemption list is read from. */
+    exemptFile: string
+    /** True when the exemption file exists and overrides `exemptProviders`. */
+    hasExemptFile: boolean
+  }
+  /**
+   * Add or remove one session id in the exemption file and apply it at once.
+   * The first call creates the file from the lists already in force, so entries
+   * visible in the UI are never dropped by a write.
+   */
+  setExemptSession(sessionId: string, exempt: boolean): ReturnType<ToolCatalogService['config']>
+  /** Re-read the exemption file, for after an external edit. */
+  reloadExempt(): ReturnType<ToolCatalogService['config']>
+  /**
+   * Persist UI-edited settings (merged per key) and apply them at once. The
+   * values win over the plugin config from the next call on. Returns the new
+   * effective configuration, in the same shape as config().
+   */
+  updateConfig(patch: ToolManagerSettings): ReturnType<ToolCatalogService['config']>
+  /** Re-read the settings file, for after an external edit. */
+  reloadConfig(): ReturnType<ToolCatalogService['config']>
+  /**
+   * Metadata of one tool as the catalog currently shows it, including which
+   * layer decided each field (`manifest`, `runtime`, `metadata` or `classifier`).
+   */
+  toolMeta(name: string): {
+    name: string
+    found: boolean
+    /** Effective values after every layer. */
+    effective: ToolMeta
+    /** Values edited from the panel, which win over the layers above. */
+    edited: ToolMeta
+    /** Values from package.json and runtime annotate() calls. */
+    declared: ToolMeta
+    group: string
+    category: string
+    summary: string
+    highRisk: boolean
+    /** The tool's directory path, for linking back to the Directory tab. */
+    path: string
+    /** True when the tool is not in the catalog (unregistered or pinned away). */
+    missing: boolean
+  }
+  /**
+   * Replace the editable metadata of one tool. Fields left out are dropped, so
+   * an emptied field falls back to the package declaration; an empty object
+   * removes the override entirely.
+   */
+  updateToolMeta(name: string, meta: ToolMeta): ReturnType<ToolCatalogService['toolMeta']>
+  /** Drop every edited field of one tool, falling back to its declaration. */
+  clearToolMeta(name: string): ReturnType<ToolCatalogService['toolMeta']>
+  /** Where edited metadata is persisted. */
+  metadataFile(): string
   packages(): PluginPackage[]
   extensions(): {
     classifiers: { name: string, priority: number }[]