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

package/lib/catalog.js

@@ -0,0 +1,311 @@
+// 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.
+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 = {
+    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, prefixCounts) {
+    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) {
+    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, max = 80) {
+    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) {
+    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, annotations) {
+    let merged;
+    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, classifiers) {
+    const byFallback = new Map();
+    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();
+    for (const [name, tools] of byFallback) {
+        const probe = { 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;
+    for (const [category, count] of votes)
+        if (!best || count > best[1])
+            best = [category, count];
+    return best?.[0];
+}
+function firstResult(classifiers, method, arg) {
+    for (const c of classifiers) {
+        const fn = c[method];
+        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;
+}
+/**
+ * Build the directory index.
+ * @param schemas - catalog tools (pinned already removed)
+ */
+export function buildCatalog(schemas, { classifiers = [], annotations = [], categories = DEFAULT_CATEGORIES, highRisk = [] } = {}) {
+    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();
+    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();
+    const groups = new Map();
+    for (const schema of schemas) {
+        const meta = annotationFor(schema.name, annotations);
+        const probe = { 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 = {
+            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 = { 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();
+    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 = (map, key) => map.get(key) ?? [...map.values()].find((v) => v.name.toLowerCase() === key);
+export function resolveTarget(catalog, raw, resolvers = []) {
+    const target = String(raw ?? '').trim();
+    for (const { prefix, resolve } of resolvers) {
+        if (prefix && !target.startsWith(prefix))
+            continue;
+        let expanded;
+        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) {
+    const byName = new Map();
+    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, node) {
+    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 [];
+}
+//# sourceMappingURL=catalog.js.map

package/lib/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"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"}

package/lib/exempt.d.ts

@@ -0,0 +1,45 @@
+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 declare function defaultExemptFile(): string;
+/** The whole file, with unknown keys dropped. */
+export declare function pickExempt(raw: unknown): ExemptConfig;
+/** Read the exemption file; missing or corrupt is "no opinion", never a crash. */
+export declare function readExemptFile(file: string, logger?: Logger): ExemptConfig | undefined;
+/** Write the file atomically, so a crash cannot leave a half-written list. */
+export declare function writeExemptFile(file: string, config: ExemptConfig, logger?: Logger): void;
+/** 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 declare function createExemptStore({ file, configProviders, logger }: {
+    file: string;
+    configProviders?: readonly string[];
+    logger?: Logger;
+}): ExemptStore;
+//# sourceMappingURL=exempt.d.ts.map

package/lib/exempt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exempt.d.ts","sourceRoot":"","sources":["../src/exempt.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAExC,iEAAiE;AACjE,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,IAAI,MAAM,CAG1C;AAQD,iDAAiD;AACjD,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,CAMrD;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAkBtF;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAUzF;AAED,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,OAAO,CAAA;IACf,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAA;IACZ,yEAAyE;IACzE,OAAO,IAAI,OAAO,CAAA;IAClB,2EAA2E;IAC3E,SAAS,IAAI,YAAY,CAAA;IACzB,2CAA2C;IAC3C,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,CAAA;IACpF,+EAA+E;IAC/E,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,YAAY,CAAA;IAC5D,gFAAgF;IAChF,MAAM,IAAI,YAAY,CAAA;CACvB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,IAAI,EAAE,eAAoB,EAAE,MAAM,EAAE,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,CA+B7J"}

package/lib/exempt.js

@@ -0,0 +1,122 @@
+// 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';
+/** Where the exemption file lives unless a deployment points elsewhere. */
+export function defaultExemptFile() {
+    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) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((name) => typeof name === 'string' && name.trim().length > 0).map((name) => name.trim());
+}
+/** The whole file, with unknown keys dropped. */
+export function pickExempt(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return { providers: [], sessions: [] };
+    const record = raw;
+    // `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, logger) {
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch (caught) {
+        const error = caught;
+        // 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.message}`);
+        return { providers: [], sessions: [] };
+    }
+}
+/** Write the file atomically, so a crash cannot leave a half-written list. */
+export function writeExemptFile(file, config, logger) {
+    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.message}`);
+        throw caught;
+    }
+}
+/**
+ * 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 }) {
+    let fromFile = readExemptFile(file, logger);
+    const effective = () => 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();
+        },
+    };
+}
+//# sourceMappingURL=exempt.js.map

package/lib/exempt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exempt.js","sourceRoot":"","sources":["../src/exempt.ts"],"names":[],"mappings":"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"}

package/lib/index.d.ts

@@ -0,0 +1,24 @@
+import type { CoreConfig, HostContext } from './types.js';
+export type * from './types.js';
+export { buildCatalog, resolveTarget, toolsUnder, estimateTokens, summary, shortName, structuralGroup, DEFAULT_CATEGORIES, UNCATEGORIZED, MISC_GROUP, OVERRIDE_PRIORITY } from './catalog.js';
+export type { BuildOptions } from './catalog.js';
+export type { RegisteredClassifier, RegisteredFilter } from './service.js';
+export type { VisibilityController, VisibilityOptions } from './visibility.js';
+export declare const name = "tool-manager";
+export declare const inject: string[];
+export declare const ENTRY_TOOLS: string[];
+export declare const HOST_RESERVED: string[];
+export declare const DEFAULT_PINNED: string[];
+export declare function apply(ctx: HostContext, config?: CoreConfig): void;
+/** Options for toolCatalog.load / tools_load. */
+export interface LoadOptions {
+    /** Also hand the targets to subagents started afterwards. */
+    forSubagents?: boolean;
+}
+declare const _default: {
+    name: string;
+    inject: string[];
+    apply: typeof apply;
+};
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAA2C,UAAU,EAAY,WAAW,EAA0F,MAAM,YAAY,CAAA;AAEpM,mBAAmB,YAAY,CAAA;AAC/B,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,cAAc,EAAE,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,kBAAkB,EAAE,aAAa,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAC7L,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAChD,YAAY,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAC1E,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAE9E,eAAO,MAAM,IAAI,iBAAiB,CAAA;AAClC,eAAO,MAAM,MAAM,UAAY,CAAA;AAE/B,eAAO,MAAM,WAAW,UAA6C,CAAA;AAMrE,eAAO,MAAM,aAAa,UAAe,CAAA;AAKzC,eAAO,MAAM,cAAc,UAY1B,CAAA;AAeD,wBAAgB,KAAK,CAAC,GAAG,EAAE,WAAW,EAAE,MAAM,GAAE,UAAe,QAmtB9D;AAED,iDAAiD;AACjD,MAAM,WAAW,WAAW;IAC1B,6DAA6D;IAC7D,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;;;;;;AAOD,wBAAsC"}