@superdoc-dev/sdk 1.0.0-alpha.4 → 1.0.0-alpha.41

package/dist/tools.js

@@ -80,24 +80,10 @@ async function loadToolNameMap() {
 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);
-    });
+/** All available tool groups from the policy. */
+export function getAvailableGroups() {
+    const policy = loadPolicy();
+    return policy.groups;
 }
 const OPERATION_INDEX = Object.fromEntries(Object.entries(CONTRACT.operations).map(([id, op]) => [id, op]));
 function validateDispatchArgs(operationId, args) {
@@ -190,26 +176,16 @@ function resolveDocApiMethod(client, operationId) {
     }
     return cursor;
 }
-export 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: [] },
-        },
-    };
+export async function getToolCatalog() {
+    return loadCatalog();
 }
-export async function listTools(provider, options = {}) {
-    const profile = options.profile ?? 'intent';
+export async function listTools(provider) {
     const bundle = await loadProviderBundle(provider);
-    const tools = bundle.profiles[profile];
+    const tools = bundle.tools;
     if (!Array.isArray(tools)) {
-        throw new SuperDocCliError('Tool provider bundle is missing profile tools.', {
+        throw new SuperDocCliError('Tool provider bundle is missing tools array.', {
             code: 'TOOLS_ASSET_INVALID',
-            details: { provider, profile },
+            details: { provider },
         });
     }
     return tools;
@@ -218,103 +194,60 @@ export async function resolveToolOperation(toolName) {
     const map = await loadToolNameMap();
     return typeof map[toolName] === 'string' ? map[toolName] : null;
 }
-export 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,
-    };
-}
+/**
+ * Select tools for a specific provider.
+ *
+ * **mode='essential'** (default): Returns only essential tools + discover_tools.
+ * Pass `groups` to additionally load all tools from those categories.
+ *
+ * **mode='all'**: Returns all tools from requested groups (or all groups if
+ * `groups` is omitted). No discover_tools included by default.
+ *
+ * @example
+ * ```ts
+ * // Default: 5 essential tools + discover_tools
+ * const { tools } = await chooseTools({ provider: 'openai' });
+ *
+ * // Essential + all comment tools
+ * const { tools } = await chooseTools({ provider: 'openai', groups: ['comments'] });
+ *
+ * // All tools (old behavior)
+ * const { tools } = await chooseTools({ provider: 'openai', mode: 'all' });
+ * ```
+ */
 export 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' });
+    const mode = input.mode ?? policy.defaults.mode ?? 'essential';
+    const includeDiscover = input.includeDiscoverTool ?? mode === 'essential';
+    let selected;
+    if (mode === 'essential') {
+        // Essential tools + any explicitly requested groups
+        const essentialNames = new Set(policy.essentialTools ?? []);
+        const requestedGroups = input.groups ? new Set(input.groups) : null;
+        selected = catalog.tools.filter((tool) => {
+            if (essentialNames.has(tool.toolName))
+                return true;
+            if (requestedGroups && requestedGroups.has(tool.category))
+                return true;
             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;
+    else {
+        // mode='all': original behavior — filter by groups
+        const alwaysInclude = new Set(policy.defaults.alwaysInclude ?? ['core']);
+        let groups;
+        if (input.groups) {
+            groups = new Set([...input.groups, ...alwaysInclude]);
         }
-        selected.push(tool);
+        else {
+            groups = new Set(policy.groups);
+        }
+        selected = catalog.tools.filter((tool) => groups.has(tool.category));
     }
+    // Build provider-formatted tools from the provider bundle
     const bundle = await loadProviderBundle(input.provider);
-    const providerTools = Array.isArray(bundle.profiles[profile]) ? bundle.profiles[profile] : [];
+    const providerTools = Array.isArray(bundle.tools) ? bundle.tools : [];
     const providerIndex = new Map(providerTools
         .filter((tool) => isRecord(tool))
         .map((tool) => [extractProviderToolName(tool), tool])
@@ -322,6 +255,14 @@ export async function chooseTools(input) {
     const selectedProviderTools = selected
         .map((tool) => providerIndex.get(tool.toolName))
         .filter((tool) => Boolean(tool));
+    // Append discover_tools if requested
+    if (includeDiscover) {
+        const discoverTool = providerIndex.get('discover_tools');
+        if (discoverTool) {
+            selectedProviderTools.push(discoverTool);
+        }
+    }
+    const resolvedGroups = mode === 'essential' ? (input.groups ?? []) : (input.groups ?? policy.groups);
     return {
         tools: selectedProviderTools,
         selected: selected.map((tool) => ({
@@ -329,17 +270,12 @@ export async function chooseTools(input) {
             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,
+        meta: {
             provider: input.provider,
+            mode,
+            groups: [...resolvedGroups],
+            selectedCount: selectedProviderTools.length,
         },
     };
 }
@@ -354,7 +290,12 @@ export async function dispatchSuperDocTool(client, toolName, args = {}, invokeOp
     if (!isRecord(args)) {
         invalidArgument(`Tool arguments for ${toolName} must be an object.`);
     }
-    validateDispatchArgs(operationId, args);
+    // Strip doc/sessionId — the SDK client manages session targeting after doc.open().
+    // Models fill these in because the tool schemas expose them, but passing them
+    // alongside an active session causes "stateless input.doc cannot be combined
+    // with a session target" errors.
+    const { doc: _doc, sessionId: _sid, ...cleanArgs } = args;
+    validateDispatchArgs(operationId, cleanArgs);
     const method = resolveDocApiMethod(client, operationId);
-    return method(args, invokeOptions);
+    return method(cleanArgs, invokeOptions);
 }

package/package.json

@@ -1,40 +1,41 @@
 {
   "name": "@superdoc-dev/sdk",
-  "version": "1.0.0-alpha.4",
+  "version": "1.0.0-alpha.41",
   "private": false,
   "type": "module",
-  "main": "./dist/index.js",
+  "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      }
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
     }
   },
   "files": [
     "dist",
+    "skills",
     "tools"
   ],
-  "optionalDependencies": {
-    "@superdoc-dev/sdk-darwin-arm64": "1.0.0-alpha.4",
-    "@superdoc-dev/sdk-darwin-x64": "1.0.0-alpha.4",
-    "@superdoc-dev/sdk-linux-arm64": "1.0.0-alpha.4",
-    "@superdoc-dev/sdk-linux-x64": "1.0.0-alpha.4",
-    "@superdoc-dev/sdk-windows-x64": "1.0.0-alpha.4"
-  },
   "devDependencies": {
     "@types/bun": "^1.3.8",
     "@types/node": "22.19.2",
+    "rollup": "^4.31.0",
     "typescript": "^5.9.2"
   },
+  "optionalDependencies": {
+    "@superdoc-dev/sdk-darwin-arm64": "1.0.0-alpha.41",
+    "@superdoc-dev/sdk-linux-x64": "1.0.0-alpha.41",
+    "@superdoc-dev/sdk-darwin-x64": "1.0.0-alpha.41",
+    "@superdoc-dev/sdk-windows-x64": "1.0.0-alpha.41",
+    "@superdoc-dev/sdk-linux-arm64": "1.0.0-alpha.41"
+  },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && rollup -c rollup.cjs.config.mjs",
     "typecheck": "tsc --noEmit"
   }
 }

package/skills/editing-docx.md

@@ -0,0 +1,31 @@
+# Editing DOCX Documents with SuperDoc SDK
+
+You are a document editing assistant using the SuperDoc SDK. You have access to tools
+that let you open, read, search, and modify `.docx` files programmatically.
+
+## Workflow
+
+1. **Open** the document with `doc.open`
+2. **Inspect** it with `doc.info` to understand structure
+3. **Find** content with `doc.find` using text search or node type queries
+4. **Modify** content using `doc.insert`, `doc.replace`, `doc.delete`, or formatting operations
+5. **Save** changes with `doc.save`
+6. **Close** when done with `doc.close`
+
+## Key Operations
+
+- `doc.find` — Search by text pattern, node type, or structured query
+- `doc.getNode` — Get a specific node by address
+- `doc.insert` — Insert text at a position
+- `doc.replace` — Replace content at a position
+- `doc.delete` — Delete content at a position
+- `doc.format.*` — Apply bold, italic, underline, strikethrough
+- `doc.comments.*` — Add, edit, resolve, remove comments
+- `doc.trackChanges.*` — Accept/reject tracked changes
+
+## Best Practices
+
+- Always open before operating, save when done
+- Use `doc.find` to locate content before modifying
+- Use `doc.info` to check document capabilities
+- Handle errors gracefully — operations may fail if targets are invalid