fix(sdk): validate tool args at dispatch boundary and fix bun export (#2405)

Author: harbournick

apps/docs/document-api/reference/ranges/index.mdx

@@ -15,3 +15,4 @@ Deterministic range construction from explicit document anchors.
 | Operation | Member path | Mutates | Idempotency | Tracked | Dry run |
 | --- | --- | --- | --- | --- | --- |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><a href="/document-api/reference/ranges/resolve"><code>ranges.resolve</code></a></span> | `ranges.resolve` | No | `idempotent` | No | No |
+

apps/docs/document-engine/sdks.mdx

@@ -376,8 +376,8 @@ The SDKs expose all operations from the [Document API](/document-api/overview) p
 | `doc.markdownToFragment` | `markdown-to-fragment` | Convert a Markdown string into an SDM/1 structural fragment. |
 | `doc.info` | `info` | Return document metadata including revision, node count, and capabilities. |
 | `doc.clearContent` | `clear-content` | Clear all document body content, leaving a single empty paragraph. |
-| `doc.insert` | `insert` | Insert inline content at a text position within an existing block, or at the end of the document when target is omitted. This is NOT for creating sibling blocks — use create.paragraph, create.heading, or lists.insert for that. Accepts two input shapes: legacy string-based (value + type) or structural SDFragment (content). Supports text (default), markdown, and html content types via the `type` field in legacy mode. Structural mode accepts an SDFragment with typed nodes (paragraphs, tables, images, etc.). |
-| `doc.replace` | `replace` | Replace content at a contiguous document selection. Text path accepts a SelectionTarget or ref plus replacement text. Structural path accepts an SDAddress, SelectionTarget, or ref plus SDFragment content. |
+| `doc.insert` | `insert` | Insert content into the document. Two input shapes: legacy string-based (value + type) inserts inline content at a text position within an existing block; structural SDFragment (content) inserts one or more blocks as siblings relative to a BlockNodeAddress target. When target is omitted, content appends at the end of the document. Legacy mode supports text (default), markdown, and html content types via the `type` field. Structural mode uses `placement` (before/after/insideStart/insideEnd) to position relative to the target block. |
+| `doc.replace` | `replace` | Replace content at a contiguous document selection. Text path accepts a SelectionTarget or ref plus replacement text. Structural path accepts a BlockNodeAddress (replaces whole block), SelectionTarget (expands to full covered block boundaries), or ref plus SDFragment content. |
 | `doc.delete` | `delete` | Delete content at a contiguous document selection. Accepts a SelectionTarget or mutation-ready ref. Supports cross-block deletion and optional block-edge expansion via behavior mode. |
 | `doc.blocks.list` | `blocks list` | List top-level blocks in document order with IDs, types, and text previews. Supports pagination via offset/limit and optional nodeType filtering. |
 | `doc.blocks.delete` | `blocks delete` | Delete an entire block node (paragraph, heading, list item, table, image, or sdt) deterministically. |
@@ -811,8 +811,8 @@ The SDKs expose all operations from the [Document API](/document-api/overview) p
 | `doc.markdown_to_fragment` | `markdown-to-fragment` | Convert a Markdown string into an SDM/1 structural fragment. |
 | `doc.info` | `info` | Return document metadata including revision, node count, and capabilities. |
 | `doc.clear_content` | `clear-content` | Clear all document body content, leaving a single empty paragraph. |
-| `doc.insert` | `insert` | Insert inline content at a text position within an existing block, or at the end of the document when target is omitted. This is NOT for creating sibling blocks — use create.paragraph, create.heading, or lists.insert for that. Accepts two input shapes: legacy string-based (value + type) or structural SDFragment (content). Supports text (default), markdown, and html content types via the `type` field in legacy mode. Structural mode accepts an SDFragment with typed nodes (paragraphs, tables, images, etc.). |
-| `doc.replace` | `replace` | Replace content at a contiguous document selection. Text path accepts a SelectionTarget or ref plus replacement text. Structural path accepts an SDAddress, SelectionTarget, or ref plus SDFragment content. |
+| `doc.insert` | `insert` | Insert content into the document. Two input shapes: legacy string-based (value + type) inserts inline content at a text position within an existing block; structural SDFragment (content) inserts one or more blocks as siblings relative to a BlockNodeAddress target. When target is omitted, content appends at the end of the document. Legacy mode supports text (default), markdown, and html content types via the `type` field. Structural mode uses `placement` (before/after/insideStart/insideEnd) to position relative to the target block. |
+| `doc.replace` | `replace` | Replace content at a contiguous document selection. Text path accepts a SelectionTarget or ref plus replacement text. Structural path accepts a BlockNodeAddress (replaces whole block), SelectionTarget (expands to full covered block boundaries), or ref plus SDFragment content. |
 | `doc.delete` | `delete` | Delete content at a contiguous document selection. Accepts a SelectionTarget or mutation-ready ref. Supports cross-block deletion and optional block-edge expansion via behavior mode. |
 | `doc.blocks.list` | `blocks list` | List top-level blocks in document order with IDs, types, and text previews. Supports pagination via offset/limit and optional nodeType filtering. |
 | `doc.blocks.delete` | `blocks delete` | Delete an entire block node (paragraph, heading, list item, table, image, or sdt) deterministically. |

packages/sdk/codegen/src/generate-intent-tools.mjs

@@ -94,6 +94,66 @@ function buildInputSchemaFromParams(operation) {
   return result;
 }
 
+// ---------------------------------------------------------------------------
+// Extract required-field constraints for an operation.
+//
+// Two sources of truth exist:
+//   1. CLI params (via buildInputSchemaFromParams) — use param names the tool
+//      schema exposes (e.g. "id", not contract's "commentId").
+//   2. Contract inputSchema — captures oneOf / discriminated-union constraints
+//      that CLI params can't express.
+//
+// Strategy:
+//   - Flat required → derive from CLI params (names match the grouped tool schema)
+//   - oneOf required → derive from contract inputSchema (property names verified
+//     to match CLI param names for all oneOf operations)
+//
+// Returns one of:
+//   { required: string[] }        — all listed keys must be present
+//   { requiredOneOf: string[][] } — at least one branch must be fully satisfied
+//   {}                            — no extractable constraints
+// ---------------------------------------------------------------------------
+
+function extractRequiredConstraints(operation) {
+  const cliSchema = buildInputSchemaFromParams(operation);
+  const cliParamNames = new Set(Object.keys(cliSchema.properties ?? {}));
+  const contractSchema = operation.inputSchema;
+
+  // oneOf in contract schema — collect per-branch required arrays.
+  // (Verified: all oneOf operations use property names matching CLI params.)
+  if (contractSchema && Array.isArray(contractSchema.oneOf)) {
+    const branches = [];
+    for (const branch of contractSchema.oneOf) {
+      if (Array.isArray(branch.oneOf)) {
+        for (const sub of branch.oneOf) {
+          if (Array.isArray(sub.required) && sub.required.length > 0) {
+            branches.push(sub.required);
+          }
+        }
+      } else if (Array.isArray(branch.required) && branch.required.length > 0) {
+        branches.push(branch.required);
+      }
+    }
+    if (branches.length > 0) return { requiredOneOf: branches };
+  }
+
+  // Flat required — union two sources:
+  //   1. Contract inputSchema.required filtered to CLI param names only
+  //      (contract is authoritative for required-ness, but may use different
+  //      property names, e.g. "commentId" vs CLI "id")
+  //   2. CLI params with required: true
+  //      (covers names that don't appear in the contract schema)
+  const required = new Set(cliSchema.required ?? []);
+  if (contractSchema && Array.isArray(contractSchema.required)) {
+    for (const key of contractSchema.required) {
+      if (cliParamNames.has(key)) required.add(key);
+    }
+  }
+  if (required.size > 0) return { required: [...required] };
+
+  return {};
+}
+
 // ---------------------------------------------------------------------------
 // Build intent tools from grouped operations
 // ---------------------------------------------------------------------------
@@ -134,7 +194,7 @@ function buildIntentTools(contract) {
         description: meta.description,
         inputSchema,
         mutates,
-        operations: [{ operationId, intentAction: operation.intentAction }],
+        operations: [{ operationId, intentAction: operation.intentAction, ...extractRequiredConstraints(operation) }],
       });
     } else {
       // Multi-op tool — add action discriminator
@@ -200,6 +260,7 @@ function buildIntentTools(contract) {
         operations: ops.map(({ operationId, operation }) => ({
           operationId,
           intentAction: operation.intentAction,
+          ...extractRequiredConstraints(operation),
         })),
       });
     }

packages/sdk/langs/node/package.json

@@ -8,7 +8,7 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "bun": "./src/index.ts",
+      "bun": "./dist/index.js",
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"

packages/sdk/langs/node/src/tools.ts

@@ -23,12 +23,19 @@ export type ToolCatalog = {
   tools: ToolCatalogEntry[];
 };
 
+type OperationEntry = {
+  operationId: string;
+  intentAction: string;
+  required?: string[];
+  requiredOneOf?: string[][];
+};
+
 type ToolCatalogEntry = {
   toolName: string;
   description: string;
   inputSchema: Record<string, unknown>;
   mutates: boolean;
-  operations: Array<{ operationId: string; intentAction: string }>;
+  operations: OperationEntry[];
 };
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -150,6 +157,106 @@ function resolveDocApiMethod(
   return cursor as (args: unknown, options?: InvokeOptions) => Promise<unknown>;
 }
 
+// Cached catalog instance — loaded once per process.
+let _catalogCache: ToolCatalog | null = null;
+
+async function getCachedCatalog(): Promise<ToolCatalog> {
+  if (_catalogCache == null) {
+    _catalogCache = await loadCatalog();
+  }
+  return _catalogCache;
+}
+
+/**
+ * Validate tool arguments against the catalog schema.
+ *
+ * Checks three things in order:
+ * 1. No unknown keys (additionalProperties: false in merged schema)
+ * 2. All universally-required keys present (merged schema `required`)
+ * 3. All action-specific required keys present (per-operation `required`)
+ */
+function validateToolArgs(toolName: string, args: Record<string, unknown>, tool: ToolCatalogEntry): void {
+  const schema = tool.inputSchema;
+  const properties = isRecord(schema.properties) ? schema.properties : {};
+  const required: string[] = Array.isArray(schema.required) ? (schema.required as string[]) : [];
+
+  // 1. Reject unknown keys
+  const knownKeys = new Set(Object.keys(properties));
+  const unknownKeys = Object.keys(args).filter((k) => !knownKeys.has(k));
+  if (unknownKeys.length > 0) {
+    throw new SuperDocCliError(`Unknown argument(s) for ${toolName}: ${unknownKeys.join(', ')}`, {
+      code: 'INVALID_ARGUMENT',
+      details: { toolName, unknownKeys, knownKeys: [...knownKeys] },
+    });
+  }
+
+  // 2. Reject missing universally-required keys
+  const missingKeys = required.filter((k) => args[k] == null);
+  if (missingKeys.length > 0) {
+    throw new SuperDocCliError(`Missing required argument(s) for ${toolName}: ${missingKeys.join(', ')}`, {
+      code: 'INVALID_ARGUMENT',
+      details: { toolName, missingKeys },
+    });
+  }
+
+  // 3. Reject missing per-operation required keys.
+  //    For multi-action tools, resolve the operation by action; for single-op
+  //    tools, use the sole operation entry.
+  const action = args.action;
+  let op: OperationEntry | undefined;
+  if (typeof action === 'string' && tool.operations.length > 1) {
+    op = tool.operations.find((o) => o.intentAction === action);
+  } else if (tool.operations.length === 1) {
+    op = tool.operations[0];
+  }
+
+  if (op) {
+    validateOperationRequired(toolName, action, args, op);
+  }
+}
+
+/**
+ * Check per-operation required constraints.
+ *
+ * Handles two shapes emitted by the codegen:
+ *   - `required: string[]`        — all listed keys must be present
+ *   - `requiredOneOf: string[][]`  — at least one branch must be fully satisfied
+ *     (mirrors JSON Schema `oneOf` with per-branch `required` arrays)
+ */
+function validateOperationRequired(
+  toolName: string,
+  action: unknown,
+  args: Record<string, unknown>,
+  op: OperationEntry,
+): void {
+  const actionLabel = typeof action === 'string' ? ` action "${action}"` : '';
+
+  if (op.requiredOneOf && op.requiredOneOf.length > 0) {
+    const satisfied = op.requiredOneOf.some((branch) => branch.every((k) => args[k] != null));
+    if (!satisfied) {
+      const options = op.requiredOneOf.map((b) => b.join(' + ')).join(' | ');
+      throw new SuperDocCliError(
+        `Missing required argument(s) for ${toolName}${actionLabel}: must provide one of: ${options}`,
+        {
+          code: 'INVALID_ARGUMENT',
+          details: { toolName, action, requiredOneOf: op.requiredOneOf },
+        },
+      );
+    }
+  } else if (op.required && op.required.length > 0) {
+    const missingActionKeys = op.required.filter((k) => args[k] == null);
+    if (missingActionKeys.length > 0) {
+      throw new SuperDocCliError(
+        `Missing required argument(s) for ${toolName}${actionLabel}: ${missingActionKeys.join(', ')}`,
+        {
+          code: 'INVALID_ARGUMENT',
+          details: { toolName, action, missingKeys: missingActionKeys },
+        },
+      );
+    }
+  }
+}
+
 export async function dispatchSuperDocTool(
   client: { doc: Record<string, unknown> },
   toolName: string,
@@ -163,6 +270,17 @@ export async function dispatchSuperDocTool(
     });
   }
 
+  // Validate against the tool schema before dispatch.
+  const catalog = await getCachedCatalog();
+  const tool = catalog.tools.find((t) => t.toolName === toolName);
+  if (tool == null) {
+    throw new SuperDocCliError(`Unknown tool: ${toolName}`, {
+      code: 'TOOL_DISPATCH_NOT_FOUND',
+      details: { toolName },
+    });
+  }
+  validateToolArgs(toolName, args, tool);
+
   // Strip doc/sessionId — the SDK client manages session targeting after doc.open().
   const { doc: _doc, sessionId: _sid, ...cleanArgs } = args;