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

package/src/tools.ts

@@ -1,701 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { CONTRACT } from './generated/contract';
-import type { InvokeOptions } from './runtime/process';
-import { SuperDocCliError } from './runtime/errors';
-
-export type ToolProvider = 'openai' | 'anthropic' | 'vercel' | 'generic';
-export type ToolProfile = 'intent' | 'operation';
-export type ToolPhase = 'read' | 'locate' | 'mutate' | 'review';
-
-export type DocumentFeatures = {
-  hasTables: boolean;
-  hasLists: boolean;
-  hasComments: boolean;
-  hasTrackedChanges: boolean;
-  isEmptyDocument: boolean;
-};
-
-export type ToolChooserInput = {
-  provider: ToolProvider;
-  profile?: ToolProfile;
-  documentFeatures?: Partial<DocumentFeatures>;
-  taskContext?: {
-    phase?: ToolPhase;
-    previousToolCalls?: Array<{ toolName: string; ok: boolean }>;
-  };
-  budget?: {
-    maxTools?: number;
-    minReadTools?: number;
-  };
-  policy?: {
-    includeCategories?: string[];
-    excludeCategories?: string[];
-    allowMutatingTools?: boolean;
-    forceInclude?: string[];
-    forceExclude?: string[];
-  };
-};
-
-export type ToolMetadata = {
-  operationId: string;
-  profile: ToolProfile;
-  mutates: boolean;
-  category: string;
-  capabilities: string[];
-  constraints?: {
-    mutuallyExclusive?: string[][];
-    requiresOneOf?: string[][];
-    requiredWhen?: Array<{
-      param: string;
-      whenParam: string;
-      equals?: unknown;
-      present?: boolean;
-    }>;
-  };
-  requiredCapabilities: Array<keyof DocumentFeatures>;
-  profileTags: string[];
-  examples: Array<{ description: string; args: Record<string, unknown> }>;
-  commandTokens: string[];
-};
-
-export type GenericToolDefinition = {
-  name: string;
-  description: string;
-  parameters: Record<string, unknown>;
-  returns: Record<string, unknown>;
-  metadata: ToolMetadata;
-};
-
-export type ToolCatalog = {
-  contractVersion: string;
-  generatedAt: string;
-  namePolicyVersion: string;
-  exposureVersion: string;
-  toolCount: number;
-  profiles: {
-    intent: {
-      name: 'intent';
-      tools: Array<{
-        operationId: string;
-        toolName: string;
-        profile: ToolProfile;
-        source: 'operation' | 'intent';
-        description: string;
-        inputSchema: Record<string, unknown>;
-        outputSchema: Record<string, unknown>;
-        mutates: boolean;
-        category: string;
-        capabilities: string[];
-        constraints?: ToolMetadata['constraints'];
-        errors: string[];
-        examples: Array<{ description: string; args: Record<string, unknown> }>;
-        commandTokens: string[];
-        profileTags: string[];
-        requiredCapabilities: Array<keyof DocumentFeatures>;
-        sessionRequirements: {
-          requiresOpenContext: boolean;
-          supportsSessionTargeting: boolean;
-        };
-        intentId?: string;
-      }>;
-    };
-    operation: {
-      name: 'operation';
-      tools: Array<{
-        operationId: string;
-        toolName: string;
-        profile: ToolProfile;
-        source: 'operation' | 'intent';
-        description: string;
-        inputSchema: Record<string, unknown>;
-        outputSchema: Record<string, unknown>;
-        mutates: boolean;
-        category: string;
-        capabilities: string[];
-        constraints?: ToolMetadata['constraints'];
-        errors: string[];
-        examples: Array<{ description: string; args: Record<string, unknown> }>;
-        commandTokens: string[];
-        profileTags: string[];
-        requiredCapabilities: Array<keyof DocumentFeatures>;
-        sessionRequirements: {
-          requiresOpenContext: boolean;
-          supportsSessionTargeting: boolean;
-        };
-        intentId?: string;
-      }>;
-    };
-  };
-};
-
-const toolsDir = path.resolve(fileURLToPath(new URL('../tools', import.meta.url)));
-const providerFileByName: Record<ToolProvider, string> = {
-  openai: 'tools.openai.json',
-  anthropic: 'tools.anthropic.json',
-  vercel: 'tools.vercel.json',
-  generic: 'tools.generic.json',
-};
-
-const DEFAULT_MAX_TOOLS_BY_PROFILE: Record<ToolProfile, number> = {
-  intent: 12,
-  operation: 16,
-};
-const DEFAULT_MIN_READ_TOOLS = 2;
-const FOUNDATIONAL_READ_OPERATION_IDS = new Set(['doc.info', 'doc.find']);
-const CHOOSER_DECISION_VERSION = 'v1';
-
-const PHASE_POLICY: Record<ToolPhase, { include: string[]; exclude: string[]; priority: string[] }> = {
-  read: {
-    include: ['introspection', 'query'],
-    exclude: ['mutation', 'trackChanges', 'session', 'create', 'comments', 'format'],
-    priority: ['query', 'introspection'],
-  },
-  locate: {
-    include: ['query'],
-    exclude: ['mutation', 'trackChanges', 'session', 'create', 'comments', 'format'],
-    priority: ['query'],
-  },
-  mutate: {
-    include: ['query', 'mutation', 'format', 'comments', 'create'],
-    exclude: ['session'],
-    priority: ['query', 'mutation', 'create', 'format', 'comments'],
-  },
-  review: {
-    include: ['query', 'trackChanges', 'comments'],
-    exclude: ['mutation', 'create', 'session', 'format'],
-    priority: ['trackChanges', 'comments', 'query'],
-  },
-};
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value != null && !Array.isArray(value);
-}
-
-function isPresent(value: unknown): boolean {
-  if (value == null) return false;
-  if (Array.isArray(value)) return value.length > 0;
-  return true;
-}
-
-function invalidArgument(message: string, details?: Record<string, unknown>): never {
-  throw new SuperDocCliError(message, {
-    code: 'INVALID_ARGUMENT',
-    details,
-  });
-}
-
-async function readJson<T>(fileName: string): Promise<T> {
-  const filePath = path.join(toolsDir, fileName);
-  let raw = '';
-  try {
-    raw = await readFile(filePath, 'utf8');
-  } catch (error) {
-    throw new 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) as T;
-  } catch (error) {
-    throw new 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: ToolProvider): Promise<{
-  contractVersion: string;
-  profiles: Record<ToolProfile, unknown[]>;
-}> {
-  return readJson<{ contractVersion: string; profiles: Record<ToolProfile, unknown[]> }>(providerFileByName[provider]);
-}
-
-async function loadToolNameMap(): Promise<Record<string, string>> {
-  return readJson<Record<string, string>>('tool-name-map.json');
-}
-
-async function loadCatalog(): Promise<ToolCatalog> {
-  return readJson<ToolCatalog>('catalog.json');
-}
-
-function normalizeFeatures(features?: Partial<DocumentFeatures>): DocumentFeatures {
-  return {
-    hasTables: Boolean(features?.hasTables),
-    hasLists: Boolean(features?.hasLists),
-    hasComments: Boolean(features?.hasComments),
-    hasTrackedChanges: Boolean(features?.hasTrackedChanges),
-    isEmptyDocument: Boolean(features?.isEmptyDocument),
-  };
-}
-
-function stableSortByPhasePriority(
-  entries: ToolCatalog['profiles']['intent']['tools'],
-  priorityOrder: string[],
-): ToolCatalog['profiles']['intent']['tools'] {
-  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);
-  });
-}
-
-function toOperationIndex(): Record<string, (typeof CONTRACT.operations)[number]> {
-  return Object.fromEntries(CONTRACT.operations.map((operation) => [operation.id, operation]));
-}
-
-const OPERATION_INDEX = toOperationIndex();
-
-function validateValueAgainstSchema(value: unknown, schema: Record<string, unknown>, path: string): void {
-  if ('const' in schema) {
-    if (value !== schema.const) {
-      invalidArgument(`${path} must equal ${JSON.stringify(schema.const)}.`);
-    }
-    return;
-  }
-
-  if (Array.isArray(schema.oneOf)) {
-    const errors: string[] = [];
-    for (const variant of schema.oneOf) {
-      if (!isRecord(variant)) continue;
-      try {
-        validateValueAgainstSchema(value, variant, path);
-        return;
-      } catch (error) {
-        errors.push(error instanceof Error ? error.message : String(error));
-      }
-    }
-
-    invalidArgument(`${path} must match one of the allowed schema variants.`, { errors });
-  }
-
-  const type = schema.type;
-  if (type === 'json') return;
-
-  if (type === 'string') {
-    if (typeof value !== 'string') invalidArgument(`${path} must be a string.`);
-    return;
-  }
-
-  if (type === 'number') {
-    if (typeof value !== 'number' || !Number.isFinite(value)) invalidArgument(`${path} must be a finite number.`);
-    return;
-  }
-
-  if (type === 'boolean') {
-    if (typeof value !== 'boolean') invalidArgument(`${path} must be a boolean.`);
-    return;
-  }
-
-  if (type === 'array') {
-    if (!Array.isArray(value)) invalidArgument(`${path} must be an array.`);
-    if (isRecord(schema.items)) {
-      for (let index = 0; index < value.length; index += 1) {
-        validateValueAgainstSchema(value[index], schema.items, `${path}[${index}]`);
-      }
-    }
-    return;
-  }
-
-  if (type === 'object') {
-    if (!isRecord(value)) invalidArgument(`${path} must be an object.`);
-
-    const properties = isRecord(schema.properties) ? schema.properties : {};
-    const required = Array.isArray(schema.required)
-      ? schema.required.filter((entry): entry is string => typeof entry === 'string')
-      : [];
-
-    for (const key of required) {
-      if (!Object.prototype.hasOwnProperty.call(value, key)) {
-        invalidArgument(`${path}.${key} is required.`);
-      }
-    }
-
-    const knownKeys = new Set(Object.keys(properties));
-    for (const key of Object.keys(value)) {
-      if (!knownKeys.has(key)) {
-        invalidArgument(`${path}.${key} is not allowed by schema.`);
-      }
-    }
-
-    for (const [key, propSchema] of Object.entries(properties)) {
-      if (!Object.prototype.hasOwnProperty.call(value, key)) continue;
-      if (!isRecord(propSchema)) continue;
-      validateValueAgainstSchema(value[key], propSchema, `${path}.${key}`);
-    }
-    return;
-  }
-}
-
-function validateDispatchArgs(operationId: string, args: Record<string, unknown>): void {
-  const operation = OPERATION_INDEX[operationId];
-  if (!operation) {
-    invalidArgument(`Unknown operation id ${operationId}.`);
-  }
-
-  const allowedParams = new Set<string>(operation.params.map((param) => String(param.name)));
-  for (const key of Object.keys(args)) {
-    if (!allowedParams.has(key)) {
-      invalidArgument(`Unexpected parameter ${key} for ${operationId}.`);
-    }
-  }
-
-  for (const param of operation.params) {
-    const value = args[param.name];
-    if (value == null) {
-      if ('required' in param && Boolean(param.required)) {
-        invalidArgument(`Missing required parameter ${param.name} for ${operationId}.`);
-      }
-      continue;
-    }
-
-    if ('schema' in param && isRecord(param.schema)) {
-      validateValueAgainstSchema(value, param.schema, `${operationId}.${param.name}`);
-      continue;
-    }
-
-    if (param.type === 'string' && typeof value !== 'string') {
-      invalidArgument(`${operationId}.${param.name} must be a string.`);
-    }
-    if (param.type === 'number' && (typeof value !== 'number' || !Number.isFinite(value))) {
-      invalidArgument(`${operationId}.${param.name} must be a finite number.`);
-    }
-    if (param.type === 'boolean' && typeof value !== 'boolean') {
-      invalidArgument(`${operationId}.${param.name} must be a boolean.`);
-    }
-    if (param.type === 'string[]') {
-      if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
-        invalidArgument(`${operationId}.${param.name} must be an array of strings.`);
-      }
-    }
-  }
-
-  const constraints = 'constraints' in operation ? operation.constraints : undefined;
-  if (!constraints) return;
-
-  const mutuallyExclusive = 'mutuallyExclusive' in constraints ? (constraints.mutuallyExclusive ?? []) : [];
-  const requiresOneOf = 'requiresOneOf' in constraints ? (constraints.requiresOneOf ?? []) : [];
-  const requiredWhen = 'requiredWhen' in constraints ? (constraints.requiredWhen ?? []) : [];
-
-  for (const group of mutuallyExclusive) {
-    const present = group.filter((name: string) => isPresent(args[name]));
-    if (present.length > 1) {
-      invalidArgument(`Arguments are mutually exclusive for ${operationId}: ${group.join(', ')}`, {
-        operationId,
-        group,
-      });
-    }
-  }
-
-  for (const group of requiresOneOf) {
-    const hasAny = group.some((name: string) => isPresent(args[name]));
-    if (!hasAny) {
-      invalidArgument(`One of the following arguments is required for ${operationId}: ${group.join(', ')}`, {
-        operationId,
-        group,
-      });
-    }
-  }
-
-  for (const rule of requiredWhen) {
-    const whenValue = args[rule.whenParam];
-    let shouldRequire = false;
-    if (Object.prototype.hasOwnProperty.call(rule, 'equals')) {
-      shouldRequire = whenValue === (rule as { equals?: unknown }).equals;
-    } else if (Object.prototype.hasOwnProperty.call(rule, 'present')) {
-      const present = (rule as { present?: boolean }).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: { doc: Record<string, unknown> }, operationId: string): (args: unknown, options?: InvokeOptions) => Promise<unknown> {
-  const tokens = operationId.split('.').slice(1);
-  let cursor: unknown = client.doc;
-
-  for (const token of tokens) {
-    if (!isRecord(cursor) || !(token in cursor)) {
-      throw new 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 SuperDocCliError(`Resolved member for ${operationId} is not callable.`, {
-      code: 'TOOL_DISPATCH_NOT_FOUND',
-      details: { operationId },
-    });
-  }
-
-  return cursor as (args: unknown, options?: InvokeOptions) => Promise<unknown>;
-}
-
-/**
- * Return a canonical view of generated tools.
- */
-export async function getToolCatalog(options: { profile?: ToolProfile } = {}): Promise<ToolCatalog> {
-  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: [] },
-    },
-  };
-}
-
-/**
- * List provider-formatted tools for the requested profile.
- */
-export async function listTools(provider: ToolProvider, options: { profile?: ToolProfile } = {}): Promise<unknown[]> {
-  const profile = options.profile ?? 'intent';
-  const bundle = await loadProviderBundle(provider);
-  const tools = bundle.profiles[profile];
-  if (!Array.isArray(tools)) {
-    throw new SuperDocCliError('Tool provider bundle is missing profile tools.', {
-      code: 'TOOLS_ASSET_INVALID',
-      details: { provider, profile },
-    });
-  }
-  return tools;
-}
-
-/**
- * Resolve a generated tool name to its canonical operation id.
- */
-export async function resolveToolOperation(toolName: string): Promise<string | null> {
-  const map = await loadToolNameMap();
-  return typeof map[toolName] === 'string' ? map[toolName] : null;
-}
-
-/**
- * Infer chooser-relevant document features from a `doc.info` response payload.
- */
-export function inferDocumentFeatures(infoResult: Record<string, unknown> | null | undefined): DocumentFeatures {
-  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,
-  };
-}
-
-/**
- * Deterministically choose a bounded tool subset for the current turn.
- */
-export async function chooseTools(input: ToolChooserInput): Promise<{
-  tools: unknown[];
-  selected: Array<{
-    operationId: string;
-    toolName: string;
-    category: string;
-    mutates: boolean;
-    profile: ToolProfile;
-  }>;
-  excluded: Array<{ toolName: string; reason: string }>;
-  selectionMeta: {
-    profile: ToolProfile;
-    phase: ToolPhase;
-    maxTools: number;
-    minReadTools: number;
-    selectedCount: number;
-    decisionVersion: string;
-    provider: ToolProvider;
-  };
-}> {
-  const catalog = await loadCatalog();
-  const profile = input.profile ?? 'intent';
-  const phase = input.taskContext?.phase ?? 'read';
-  const phasePolicy = PHASE_POLICY[phase];
-  const featureMap = normalizeFeatures(input.documentFeatures);
-
-  const maxTools = Math.max(1, input.budget?.maxTools ?? DEFAULT_MAX_TOOLS_BY_PROFILE[profile]);
-  const minReadTools = Math.max(0, input.budget?.minReadTools ?? DEFAULT_MIN_READ_TOOLS);
-
-  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: Array<{ toolName: string; reason: string }> = [];
-
-  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: typeof profileTools = [];
-  const foundational = candidates.filter((tool) => FOUNDATIONAL_READ_OPERATION_IDS.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): tool is Record<string, unknown> => isRecord(tool) && typeof tool.name === 'string')
-      .map((tool) => [tool.name as string, tool]),
-  );
-
-  const selectedProviderTools = selected
-    .map((tool) => providerIndex.get(tool.toolName))
-    .filter((tool): tool is Record<string, unknown> => 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: CHOOSER_DECISION_VERSION,
-      provider: input.provider,
-    },
-  };
-}
-
-/**
- * Dispatch a SuperDoc tool call to the canonical SDK `client.doc.*` operation.
- */
-export async function dispatchSuperDocTool(
-  client: { doc: Record<string, unknown> },
-  toolName: string,
-  args: Record<string, unknown> = {},
-  invokeOptions?: InvokeOptions,
-): Promise<unknown> {
-  const operationId = await resolveToolOperation(toolName);
-  if (!operationId) {
-    throw new 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);
-}