@superdoc-dev/sdk 1.0.0-alpha.2 → 1.0.0-alpha.22

package/dist/skills.cjs

@@ -0,0 +1,148 @@
+'use strict';
+
+var node_fs = require('node:fs');
+var os = require('node:os');
+var path = require('node:path');
+var node_url = require('node:url');
+var errors = require('./runtime/errors.cjs');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+// Resolve skills directory relative to package root (works from both src/ and dist/)
+const skillsDir = path.resolve(path.dirname(node_url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('skills.cjs', document.baseURI).href)))), '..', 'skills');
+const SKILL_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+const SUPPORTED_SKILL_RUNTIMES = ['claude'];
+const SUPPORTED_INSTALL_SCOPES = ['project', 'user'];
+function resolveSkillFilePath(skillName) {
+    const filePath = path.resolve(skillsDir, `${skillName}.md`);
+    const root = `${skillsDir}${path.sep}`;
+    if (!filePath.startsWith(root)) {
+        throw new errors.SuperDocCliError('Skill name resolved outside SDK skill directory.', {
+            code: 'INVALID_ARGUMENT',
+            details: { skillName },
+        });
+    }
+    return filePath;
+}
+function normalizeSkillName(name) {
+    const normalized = name.trim();
+    if (!normalized || !SKILL_NAME_RE.test(normalized)) {
+        throw new errors.SuperDocCliError('Skill name is required.', {
+            code: 'INVALID_ARGUMENT',
+            details: { name },
+        });
+    }
+    return normalized;
+}
+function listSkills() {
+    try {
+        return node_fs.readdirSync(skillsDir)
+            .filter((entry) => path.extname(entry) === '.md')
+            .map((entry) => path.basename(entry, '.md'))
+            .sort();
+    }
+    catch (error) {
+        throw new errors.SuperDocCliError('Unable to enumerate SDK skills.', {
+            code: 'SKILL_IO_ERROR',
+            details: {
+                skillsDir,
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+}
+function getSkill(name) {
+    const normalized = normalizeSkillName(name);
+    const filePath = resolveSkillFilePath(normalized);
+    try {
+        return node_fs.readFileSync(filePath, 'utf8');
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError?.code === 'ENOENT') {
+            let available = [];
+            try {
+                available = listSkills();
+            }
+            catch {
+                // Keep available empty
+            }
+            throw new errors.SuperDocCliError('Requested SDK skill was not found.', {
+                code: 'SKILL_NOT_FOUND',
+                details: { name: normalized, available },
+            });
+        }
+        throw new errors.SuperDocCliError('Unable to read SDK skill file.', {
+            code: 'SKILL_IO_ERROR',
+            details: {
+                name: normalized,
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+}
+function installSkill(name, options = {}) {
+    const normalizedName = normalizeSkillName(name);
+    const runtime = options.runtime ?? 'claude';
+    if (!SUPPORTED_SKILL_RUNTIMES.includes(runtime)) {
+        throw new errors.SuperDocCliError('Unsupported skill runtime.', {
+            code: 'INVALID_ARGUMENT',
+            details: { runtime, supportedRuntimes: [...SUPPORTED_SKILL_RUNTIMES] },
+        });
+    }
+    const scope = options.scope ?? 'project';
+    if (!SUPPORTED_INSTALL_SCOPES.includes(scope)) {
+        throw new errors.SuperDocCliError('Unsupported skill install scope.', {
+            code: 'INVALID_ARGUMENT',
+            details: { scope, supportedScopes: [...SUPPORTED_INSTALL_SCOPES] },
+        });
+    }
+    const skillsRoot = options.targetDir !== undefined
+        ? path.resolve(options.targetDir)
+        : scope === 'user'
+            ? path.resolve(options.homeDir ?? os.homedir(), '.claude', 'skills')
+            : path.resolve(options.cwd ?? process.cwd(), '.claude', 'skills');
+    const skillFile = path.join(skillsRoot, normalizedName, 'SKILL.md');
+    const overwrite = options.overwrite ?? true;
+    const alreadyExists = node_fs.existsSync(skillFile);
+    if (!overwrite && alreadyExists) {
+        return {
+            name: normalizedName,
+            runtime,
+            scope: options.targetDir !== undefined ? 'custom' : scope,
+            path: skillFile,
+            written: false,
+            overwritten: false,
+        };
+    }
+    try {
+        const content = getSkill(name);
+        node_fs.mkdirSync(path.dirname(skillFile), { recursive: true });
+        node_fs.writeFileSync(skillFile, content, 'utf8');
+    }
+    catch (error) {
+        if (error instanceof errors.SuperDocCliError)
+            throw error;
+        throw new errors.SuperDocCliError('Unable to install SDK skill.', {
+            code: 'SKILL_IO_ERROR',
+            details: {
+                name: normalizedName,
+                runtime,
+                scope: options.targetDir !== undefined ? 'custom' : scope,
+                path: skillFile,
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+    return {
+        name: normalizedName,
+        runtime,
+        scope: options.targetDir !== undefined ? 'custom' : scope,
+        path: skillFile,
+        written: true,
+        overwritten: alreadyExists,
+    };
+}
+
+exports.getSkill = getSkill;
+exports.installSkill = installSkill;
+exports.listSkills = listSkills;

package/dist/skills.d.ts

@@ -0,0 +1,25 @@
+declare const SUPPORTED_SKILL_RUNTIMES: readonly ["claude"];
+declare const SUPPORTED_INSTALL_SCOPES: readonly ["project", "user"];
+type SkillRuntime = (typeof SUPPORTED_SKILL_RUNTIMES)[number];
+type SkillInstallScope = (typeof SUPPORTED_INSTALL_SCOPES)[number];
+export interface InstallSkillOptions {
+    runtime?: SkillRuntime;
+    scope?: SkillInstallScope;
+    targetDir?: string;
+    cwd?: string;
+    homeDir?: string;
+    overwrite?: boolean;
+}
+export interface InstalledSkillResult {
+    name: string;
+    runtime: SkillRuntime;
+    scope: SkillInstallScope | 'custom';
+    path: string;
+    written: boolean;
+    overwritten: boolean;
+}
+export declare function listSkills(): string[];
+export declare function getSkill(name: string): string;
+export declare function installSkill(name: string, options?: InstallSkillOptions): InstalledSkillResult;
+export {};
+//# sourceMappingURL=skills.d.ts.map

package/dist/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AASA,QAAA,MAAM,wBAAwB,qBAAsB,CAAC;AACrD,QAAA,MAAM,wBAAwB,8BAA+B,CAAC;AAE9D,KAAK,YAAY,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC9D,KAAK,iBAAiB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;IACtB,KAAK,EAAE,iBAAiB,GAAG,QAAQ,CAAC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;CACtB;AAyBD,wBAAgB,UAAU,IAAI,MAAM,EAAE,CAerC;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA4B7C;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,oBAAoB,CAmElG"}

package/dist/skills.js

@@ -0,0 +1,140 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SuperDocCliError } from './runtime/errors.js';
+// Resolve skills directory relative to package root (works from both src/ and dist/)
+const skillsDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'skills');
+const SKILL_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+const SUPPORTED_SKILL_RUNTIMES = ['claude'];
+const SUPPORTED_INSTALL_SCOPES = ['project', 'user'];
+function resolveSkillFilePath(skillName) {
+    const filePath = path.resolve(skillsDir, `${skillName}.md`);
+    const root = `${skillsDir}${path.sep}`;
+    if (!filePath.startsWith(root)) {
+        throw new SuperDocCliError('Skill name resolved outside SDK skill directory.', {
+            code: 'INVALID_ARGUMENT',
+            details: { skillName },
+        });
+    }
+    return filePath;
+}
+function normalizeSkillName(name) {
+    const normalized = name.trim();
+    if (!normalized || !SKILL_NAME_RE.test(normalized)) {
+        throw new SuperDocCliError('Skill name is required.', {
+            code: 'INVALID_ARGUMENT',
+            details: { name },
+        });
+    }
+    return normalized;
+}
+export function listSkills() {
+    try {
+        return readdirSync(skillsDir)
+            .filter((entry) => path.extname(entry) === '.md')
+            .map((entry) => path.basename(entry, '.md'))
+            .sort();
+    }
+    catch (error) {
+        throw new SuperDocCliError('Unable to enumerate SDK skills.', {
+            code: 'SKILL_IO_ERROR',
+            details: {
+                skillsDir,
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+}
+export function getSkill(name) {
+    const normalized = normalizeSkillName(name);
+    const filePath = resolveSkillFilePath(normalized);
+    try {
+        return readFileSync(filePath, 'utf8');
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError?.code === 'ENOENT') {
+            let available = [];
+            try {
+                available = listSkills();
+            }
+            catch {
+                // Keep available empty
+            }
+            throw new SuperDocCliError('Requested SDK skill was not found.', {
+                code: 'SKILL_NOT_FOUND',
+                details: { name: normalized, available },
+            });
+        }
+        throw new SuperDocCliError('Unable to read SDK skill file.', {
+            code: 'SKILL_IO_ERROR',
+            details: {
+                name: normalized,
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+}
+export function installSkill(name, options = {}) {
+    const normalizedName = normalizeSkillName(name);
+    const runtime = options.runtime ?? 'claude';
+    if (!SUPPORTED_SKILL_RUNTIMES.includes(runtime)) {
+        throw new SuperDocCliError('Unsupported skill runtime.', {
+            code: 'INVALID_ARGUMENT',
+            details: { runtime, supportedRuntimes: [...SUPPORTED_SKILL_RUNTIMES] },
+        });
+    }
+    const scope = options.scope ?? 'project';
+    if (!SUPPORTED_INSTALL_SCOPES.includes(scope)) {
+        throw new SuperDocCliError('Unsupported skill install scope.', {
+            code: 'INVALID_ARGUMENT',
+            details: { scope, supportedScopes: [...SUPPORTED_INSTALL_SCOPES] },
+        });
+    }
+    const skillsRoot = options.targetDir !== undefined
+        ? path.resolve(options.targetDir)
+        : scope === 'user'
+            ? path.resolve(options.homeDir ?? os.homedir(), '.claude', 'skills')
+            : path.resolve(options.cwd ?? process.cwd(), '.claude', 'skills');
+    const skillFile = path.join(skillsRoot, normalizedName, 'SKILL.md');
+    const overwrite = options.overwrite ?? true;
+    const alreadyExists = existsSync(skillFile);
+    if (!overwrite && alreadyExists) {
+        return {
+            name: normalizedName,
+            runtime,
+            scope: options.targetDir !== undefined ? 'custom' : scope,
+            path: skillFile,
+            written: false,
+            overwritten: false,
+        };
+    }
+    try {
+        const content = getSkill(name);
+        mkdirSync(path.dirname(skillFile), { recursive: true });
+        writeFileSync(skillFile, content, 'utf8');
+    }
+    catch (error) {
+        if (error instanceof SuperDocCliError)
+            throw error;
+        throw new SuperDocCliError('Unable to install SDK skill.', {
+            code: 'SKILL_IO_ERROR',
+            details: {
+                name: normalizedName,
+                runtime,
+                scope: options.targetDir !== undefined ? 'custom' : scope,
+                path: skillFile,
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+    return {
+        name: normalizedName,
+        runtime,
+        scope: options.targetDir !== undefined ? 'custom' : scope,
+        path: skillFile,
+        written: true,
+        overwritten: alreadyExists,
+    };
+}

package/dist/tools.cjs

@@ -0,0 +1,371 @@
+'use strict';
+
+var promises = require('node:fs/promises');
+var node_fs = require('node:fs');
+var path = require('node:path');
+var node_url = require('node:url');
+var contract = require('./generated/contract.cjs');
+var errors = require('./runtime/errors.cjs');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+// Resolve tools directory relative to package root (works from both src/ and dist/)
+const toolsDir = path.resolve(path.dirname(node_url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('tools.cjs', document.baseURI).href)))), '..', 'tools');
+const providerFileByName = {
+    openai: 'tools.openai.json',
+    anthropic: 'tools.anthropic.json',
+    vercel: 'tools.vercel.json',
+    generic: 'tools.generic.json',
+};
+let _policyCache = null;
+function loadPolicy() {
+    if (_policyCache)
+        return _policyCache;
+    const raw = node_fs.readFileSync(path.join(toolsDir, 'tools-policy.json'), 'utf8');
+    _policyCache = JSON.parse(raw);
+    return _policyCache;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value != null && !Array.isArray(value);
+}
+function isPresent(value) {
+    if (value == null)
+        return false;
+    if (Array.isArray(value))
+        return value.length > 0;
+    return true;
+}
+function extractProviderToolName(tool) {
+    // Anthropic / Generic: top-level name
+    if (typeof tool.name === 'string')
+        return tool.name;
+    // OpenAI / Vercel: nested under function.name
+    if (isRecord(tool.function) && typeof tool.function.name === 'string') {
+        return tool.function.name;
+    }
+    return null;
+}
+function invalidArgument(message, details) {
+    throw new errors.SuperDocCliError(message, { code: 'INVALID_ARGUMENT', details });
+}
+async function readJson(fileName) {
+    const filePath = path.join(toolsDir, fileName);
+    let raw = '';
+    try {
+        raw = await promises.readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        throw new errors.SuperDocCliError('Unable to load packaged tool artifact.', {
+            code: 'TOOLS_ASSET_NOT_FOUND',
+            details: {
+                filePath,
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new errors.SuperDocCliError('Packaged tool artifact is invalid JSON.', {
+            code: 'TOOLS_ASSET_INVALID',
+            details: {
+                filePath,
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+}
+async function loadProviderBundle(provider) {
+    return readJson(providerFileByName[provider]);
+}
+async function loadToolNameMap() {
+    return readJson('tool-name-map.json');
+}
+async function loadCatalog() {
+    return readJson('catalog.json');
+}
+function normalizeFeatures(features) {
+    return {
+        hasTables: Boolean(features?.hasTables),
+        hasLists: Boolean(features?.hasLists),
+        hasComments: Boolean(features?.hasComments),
+        hasTrackedChanges: Boolean(features?.hasTrackedChanges),
+        isEmptyDocument: Boolean(features?.isEmptyDocument),
+    };
+}
+function stableSortByPhasePriority(entries, priorityOrder) {
+    const priority = new Map(priorityOrder.map((category, index) => [category, index]));
+    return [...entries].sort((a, b) => {
+        const aPriority = priority.get(a.category) ?? Number.MAX_SAFE_INTEGER;
+        const bPriority = priority.get(b.category) ?? Number.MAX_SAFE_INTEGER;
+        if (aPriority !== bPriority)
+            return aPriority - bPriority;
+        return a.toolName.localeCompare(b.toolName);
+    });
+}
+const OPERATION_INDEX = Object.fromEntries(Object.entries(contract.CONTRACT.operations).map(([id, op]) => [id, op]));
+function validateDispatchArgs(operationId, args) {
+    const operation = OPERATION_INDEX[operationId];
+    if (!operation) {
+        invalidArgument(`Unknown operation id ${operationId}.`);
+    }
+    // Unknown-param rejection
+    const allowedParams = new Set(operation.params.map((param) => String(param.name)));
+    for (const key of Object.keys(args)) {
+        if (!allowedParams.has(key)) {
+            invalidArgument(`Unexpected parameter ${key} for ${operationId}.`);
+        }
+    }
+    // Required-param enforcement
+    for (const param of operation.params) {
+        if ('required' in param && Boolean(param.required) && args[param.name] == null) {
+            invalidArgument(`Missing required parameter ${param.name} for ${operationId}.`);
+        }
+    }
+    // Constraint validation (CLI handles schema-level type validation authoritatively)
+    const constraints = 'constraints' in operation ? operation.constraints : undefined;
+    if (!constraints || !isRecord(constraints))
+        return;
+    const mutuallyExclusive = Array.isArray(constraints.mutuallyExclusive) ? constraints.mutuallyExclusive : [];
+    const requiresOneOf = Array.isArray(constraints.requiresOneOf) ? constraints.requiresOneOf : [];
+    const requiredWhen = Array.isArray(constraints.requiredWhen) ? constraints.requiredWhen : [];
+    for (const group of mutuallyExclusive) {
+        if (!Array.isArray(group))
+            continue;
+        const present = group.filter((name) => isPresent(args[name]));
+        if (present.length > 1) {
+            invalidArgument(`Arguments are mutually exclusive for ${operationId}: ${group.join(', ')}`, {
+                operationId,
+                group,
+            });
+        }
+    }
+    for (const group of requiresOneOf) {
+        if (!Array.isArray(group))
+            continue;
+        const hasAny = group.some((name) => isPresent(args[name]));
+        if (!hasAny) {
+            invalidArgument(`One of the following arguments is required for ${operationId}: ${group.join(', ')}`, {
+                operationId,
+                group,
+            });
+        }
+    }
+    for (const rule of requiredWhen) {
+        if (!isRecord(rule))
+            continue;
+        const whenValue = args[rule.whenParam];
+        let shouldRequire = false;
+        if (Object.prototype.hasOwnProperty.call(rule, 'equals')) {
+            shouldRequire = whenValue === rule.equals;
+        }
+        else if (Object.prototype.hasOwnProperty.call(rule, 'present')) {
+            const present = rule.present === true;
+            shouldRequire = present ? isPresent(whenValue) : !isPresent(whenValue);
+        }
+        else {
+            shouldRequire = isPresent(whenValue);
+        }
+        if (shouldRequire && !isPresent(args[rule.param])) {
+            invalidArgument(`Argument ${rule.param} is required by constraints for ${operationId}.`, {
+                operationId,
+                rule,
+            });
+        }
+    }
+}
+function resolveDocApiMethod(client, operationId) {
+    const tokens = operationId.split('.').slice(1);
+    let cursor = client.doc;
+    for (const token of tokens) {
+        if (!isRecord(cursor) || !(token in cursor)) {
+            throw new errors.SuperDocCliError(`No SDK doc method found for operation ${operationId}.`, {
+                code: 'TOOL_DISPATCH_NOT_FOUND',
+                details: { operationId, token },
+            });
+        }
+        cursor = cursor[token];
+    }
+    if (typeof cursor !== 'function') {
+        throw new errors.SuperDocCliError(`Resolved member for ${operationId} is not callable.`, {
+            code: 'TOOL_DISPATCH_NOT_FOUND',
+            details: { operationId },
+        });
+    }
+    return cursor;
+}
+async function getToolCatalog(options = {}) {
+    const catalog = await loadCatalog();
+    if (!options.profile)
+        return catalog;
+    return {
+        ...catalog,
+        profiles: {
+            intent: options.profile === 'intent' ? catalog.profiles.intent : { name: 'intent', tools: [] },
+            operation: options.profile === 'operation' ? catalog.profiles.operation : { name: 'operation', tools: [] },
+        },
+    };
+}
+async function listTools(provider, options = {}) {
+    const profile = options.profile ?? 'intent';
+    const bundle = await loadProviderBundle(provider);
+    const tools = bundle.profiles[profile];
+    if (!Array.isArray(tools)) {
+        throw new errors.SuperDocCliError('Tool provider bundle is missing profile tools.', {
+            code: 'TOOLS_ASSET_INVALID',
+            details: { provider, profile },
+        });
+    }
+    return tools;
+}
+async function resolveToolOperation(toolName) {
+    const map = await loadToolNameMap();
+    return typeof map[toolName] === 'string' ? map[toolName] : null;
+}
+function inferDocumentFeatures(infoResult) {
+    if (!isRecord(infoResult)) {
+        return {
+            hasTables: false,
+            hasLists: false,
+            hasComments: false,
+            hasTrackedChanges: false,
+            isEmptyDocument: false,
+        };
+    }
+    const counts = isRecord(infoResult.counts) ? infoResult.counts : {};
+    const words = typeof counts.words === 'number' ? counts.words : 0;
+    const paragraphs = typeof counts.paragraphs === 'number' ? counts.paragraphs : 0;
+    const tables = typeof counts.tables === 'number' ? counts.tables : 0;
+    const comments = typeof counts.comments === 'number' ? counts.comments : 0;
+    const lists = typeof counts.lists === 'number' ? counts.lists : typeof counts.listItems === 'number' ? counts.listItems : 0;
+    const trackedChanges = typeof counts.trackedChanges === 'number'
+        ? counts.trackedChanges
+        : typeof counts.tracked_changes === 'number'
+            ? counts.tracked_changes
+            : 0;
+    return {
+        hasTables: tables > 0,
+        hasLists: lists > 0,
+        hasComments: comments > 0,
+        hasTrackedChanges: trackedChanges > 0,
+        isEmptyDocument: words === 0 && paragraphs <= 1,
+    };
+}
+async function chooseTools(input) {
+    const catalog = await loadCatalog();
+    const policy = loadPolicy();
+    const profile = input.profile ?? 'intent';
+    const phase = input.taskContext?.phase ?? 'read';
+    const phasePolicy = policy.phases[phase];
+    const featureMap = normalizeFeatures(input.documentFeatures);
+    const maxTools = Math.max(1, input.budget?.maxTools ?? policy.defaults.maxToolsByProfile[profile]);
+    const minReadTools = Math.max(0, input.budget?.minReadTools ?? policy.defaults.minReadTools);
+    const includeCategories = new Set(input.policy?.includeCategories ?? phasePolicy.include);
+    const excludeCategories = new Set([...(input.policy?.excludeCategories ?? []), ...phasePolicy.exclude]);
+    const allowMutatingTools = input.policy?.allowMutatingTools ?? phase === 'mutate';
+    const excluded = [];
+    const profileTools = catalog.profiles[profile].tools;
+    const indexByToolName = new Map(profileTools.map((tool) => [tool.toolName, tool]));
+    let candidates = profileTools.filter((tool) => {
+        if (tool.requiredCapabilities.some((capability) => !featureMap[capability])) {
+            excluded.push({ toolName: tool.toolName, reason: 'missing-required-capability' });
+            return false;
+        }
+        if (!allowMutatingTools && tool.mutates) {
+            excluded.push({ toolName: tool.toolName, reason: 'mutations-disabled' });
+            return false;
+        }
+        if (includeCategories.size > 0 && !includeCategories.has(tool.category)) {
+            excluded.push({ toolName: tool.toolName, reason: 'category-not-included' });
+            return false;
+        }
+        if (excludeCategories.has(tool.category)) {
+            excluded.push({ toolName: tool.toolName, reason: 'phase-category-excluded' });
+            return false;
+        }
+        return true;
+    });
+    const forceExclude = new Set(input.policy?.forceExclude ?? []);
+    candidates = candidates.filter((tool) => {
+        if (!forceExclude.has(tool.toolName))
+            return true;
+        excluded.push({ toolName: tool.toolName, reason: 'force-excluded' });
+        return false;
+    });
+    for (const forcedToolName of input.policy?.forceInclude ?? []) {
+        const forced = indexByToolName.get(forcedToolName);
+        if (!forced) {
+            excluded.push({ toolName: forcedToolName, reason: 'not-in-profile' });
+            continue;
+        }
+        candidates.push(forced);
+    }
+    candidates = [...new Map(candidates.map((tool) => [tool.toolName, tool])).values()];
+    const selected = [];
+    const foundationalIds = new Set(policy.defaults.foundationalOperationIds);
+    const foundational = candidates.filter((tool) => foundationalIds.has(tool.operationId));
+    for (const tool of foundational) {
+        if (selected.length >= minReadTools || selected.length >= maxTools)
+            break;
+        selected.push(tool);
+    }
+    const remaining = stableSortByPhasePriority(candidates.filter((tool) => !selected.some((entry) => entry.toolName === tool.toolName)), phasePolicy.priority);
+    for (const tool of remaining) {
+        if (selected.length >= maxTools) {
+            excluded.push({ toolName: tool.toolName, reason: 'budget-trim' });
+            continue;
+        }
+        selected.push(tool);
+    }
+    const bundle = await loadProviderBundle(input.provider);
+    const providerTools = Array.isArray(bundle.profiles[profile]) ? bundle.profiles[profile] : [];
+    const providerIndex = new Map(providerTools
+        .filter((tool) => isRecord(tool))
+        .map((tool) => [extractProviderToolName(tool), tool])
+        .filter((entry) => entry[0] !== null));
+    const selectedProviderTools = selected
+        .map((tool) => providerIndex.get(tool.toolName))
+        .filter((tool) => Boolean(tool));
+    return {
+        tools: selectedProviderTools,
+        selected: selected.map((tool) => ({
+            operationId: tool.operationId,
+            toolName: tool.toolName,
+            category: tool.category,
+            mutates: tool.mutates,
+            profile: tool.profile,
+        })),
+        excluded,
+        selectionMeta: {
+            profile,
+            phase,
+            maxTools,
+            minReadTools,
+            selectedCount: selected.length,
+            decisionVersion: policy.defaults.chooserDecisionVersion,
+            provider: input.provider,
+        },
+    };
+}
+async function dispatchSuperDocTool(client, toolName, args = {}, invokeOptions) {
+    const operationId = await resolveToolOperation(toolName);
+    if (!operationId) {
+        throw new errors.SuperDocCliError(`Unknown SuperDoc tool: ${toolName}`, {
+            code: 'TOOL_NOT_FOUND',
+            details: { toolName },
+        });
+    }
+    if (!isRecord(args)) {
+        invalidArgument(`Tool arguments for ${toolName} must be an object.`);
+    }
+    validateDispatchArgs(operationId, args);
+    const method = resolveDocApiMethod(client, operationId);
+    return method(args, invokeOptions);
+}
+
+exports.chooseTools = chooseTools;
+exports.dispatchSuperDocTool = dispatchSuperDocTool;
+exports.getToolCatalog = getToolCatalog;
+exports.inferDocumentFeatures = inferDocumentFeatures;
+exports.listTools = listTools;
+exports.resolveToolOperation = resolveToolOperation;