@pedrofariasx/qwenproxy 1.1.0

package/src/tools/registry.ts

@@ -0,0 +1,142 @@
+/*
+ * File: registry.ts
+ * Project: qwenproxy
+ * Tool registry with register/lookup and OpenAI-compatible schema export
+ */
+
+import type {
+  FunctionToolDefinition,
+  JsonSchema,
+  ToolContext,
+  ToolHandler,
+  ToolRegistration,
+} from './types';
+import { validateAgainstSchema } from './schema.js';
+
+/**
+ * Central tool registry. Tools are registered at startup and looked up by name
+ * during the execution loop.
+ */
+export class ToolRegistry {
+  private tools = new Map<string, ToolRegistration>();
+
+  /**
+   * Register a new tool.
+   * @param name        Unique tool name (must match the function name the LLM will emit)
+   * @param description Human-readable description (sent to the LLM)
+   * @param parameters  JSON Schema describing the tool's parameters
+   * @param handler     Async function that executes the tool
+   * @param strict      When true, additionalProperties:false is enforced and
+   *                    missing required fields are rejected (default true)
+   */
+  register<TArgs = any, TResult = any>(
+    name: string,
+    description: string,
+    parameters: JsonSchema,
+    handler: ToolHandler<TArgs, TResult>,
+    strict = true
+  ): void {
+    if (this.tools.has(name)) {
+      throw new Error(`Tool '${name}' is already registered`);
+    }
+
+    // If strict mode, ensure the schema enforces additionalProperties: false
+    const enforcedParams = strict
+      ? { ...parameters, additionalProperties: false }
+      : parameters;
+
+    this.tools.set(name, {
+      name,
+      description,
+      parameters: enforcedParams,
+      strict,
+      handler: handler as ToolHandler,
+    });
+  }
+
+  /**
+   * Unregister a tool by name. Useful for testing.
+   */
+  unregister(name: string): boolean {
+    return this.tools.delete(name);
+  }
+
+  /**
+   * Look up a tool by name. Returns undefined if not found.
+   */
+  get(name: string): ToolRegistration | undefined {
+    return this.tools.get(name);
+  }
+
+  /**
+   * Check whether a tool with the given name exists.
+   */
+  has(name: string): boolean {
+    return this.tools.has(name);
+  }
+
+  /**
+   * Return all registered tool names.
+   */
+  listNames(): string[] {
+    return Array.from(this.tools.keys());
+  }
+
+  /**
+   * Return the OpenAI-compatible tool definitions array
+   * (for inclusion in the `tools` field of the request body sent to the LLM).
+   */
+  toOpenAITools(): FunctionToolDefinition[] {
+    const defs: FunctionToolDefinition[] = [];
+    for (const tool of this.tools.values()) {
+      defs.push({
+        type: 'function',
+        function: {
+          name: tool.name,
+          description: tool.description,
+          parameters: tool.parameters,
+          strict: tool.strict,
+        },
+      });
+    }
+    return defs;
+  }
+
+  /**
+   * Validate a tool call's arguments against the registered schema, then
+   * invoke the handler. Returns a serialised result string.
+   *
+   * @throws SchemaValidationError if validation fails
+   * @throws Error if the tool is not found
+   */
+  async execute(
+    toolName: string,
+    rawArgs: Record<string, unknown>,
+    context: ToolContext
+  ): Promise<string> {
+    const registration = this.tools.get(toolName);
+    if (!registration) {
+      throw new Error(`Unknown tool: '${toolName}'`);
+    }
+
+    // Strict validation
+    const validatedArgs = validateAgainstSchema(
+      rawArgs,
+      registration.parameters,
+      `$.${toolName}`
+    ) as Record<string, unknown>;
+
+    const result = await registration.handler(validatedArgs, context);
+
+    // Serialize result
+    if (typeof result === 'string') {
+      return result;
+    }
+    return JSON.stringify(result, null, 2);
+  }
+}
+
+/**
+ * Singleton registry instance shared across the application.
+ */
+export const registry = new ToolRegistry();

package/src/tools/repair.ts

@@ -0,0 +1,42 @@
+export interface RepairedTool {
+  name: string;
+  arguments: unknown;
+}
+
+export function repairToolCall(extracted: Record<string, unknown>): RepairedTool | null {
+  if ('tool' in extracted && !('name' in extracted)) {
+    return {
+      name: String(extracted.tool),
+      arguments: extracted.arguments || {},
+    };
+  }
+
+  if ('function' in extracted && typeof extracted.function === 'object' && extracted.function !== null) {
+    const fn = extracted.function as Record<string, unknown>;
+    if ('name' in fn) {
+      return {
+        name: String(fn.name),
+        arguments: fn.arguments || {},
+      };
+    }
+  }
+
+  if ('function_call' in extracted && typeof extracted.function_call === 'object' && extracted.function_call !== null) {
+    const fn = extracted.function_call as Record<string, unknown>;
+    if ('name' in fn) {
+      return {
+        name: String(fn.name),
+        arguments: fn.arguments || {},
+      };
+    }
+  }
+
+  if ('name' in extracted) {
+    return {
+      name: String(extracted.name),
+      arguments: extracted.arguments || {},
+    };
+  }
+
+  return null;
+}

package/src/tools/schema.ts

@@ -0,0 +1,285 @@
+/*
+ * File: schema.ts
+ * Project: qwenproxy
+ * Strict JSON Schema validator for tool calling
+ */
+
+import type { JsonSchema } from './types';
+
+/**
+ * Error thrown when schema validation fails.
+ */
+export class SchemaValidationError extends Error {
+  public readonly path: string;
+  public readonly value: unknown;
+
+  constructor(message: string, path: string, value?: unknown) {
+    super(message);
+    this.name = 'SchemaValidationError';
+    this.path = path;
+    this.value = value;
+  }
+}
+
+/**
+ * Validates a value against a JSON Schema with strict type checking.
+ * Throws SchemaValidationError on failure.
+ * Returns the validated (possibly coerced) value on success.
+ */
+export function validateAgainstSchema(
+  value: unknown,
+  schema: JsonSchema,
+  path: string = '$'
+): unknown {
+  // Handle nullable schemas
+  if (schema.nullable && (value === null || value === undefined)) {
+    return value;
+  }
+
+  switch (schema.type) {
+    case 'object':
+      return validateObject(value, schema, path);
+    case 'array':
+      return validateArray(value, schema, path);
+    case 'string':
+      return validateString(value, schema, path);
+    case 'number':
+    case 'integer':
+      return validateNumber(value, schema, path);
+    case 'boolean':
+      return validateBoolean(value, schema, path);
+    case 'null':
+      if (value !== null) {
+        throw new SchemaValidationError(
+          `Expected null at ${path}, got ${typeof value}`,
+          path,
+          value
+        );
+      }
+      return null;
+    default:
+      return value;
+  }
+}
+
+function validateObject(
+  value: unknown,
+  schema: JsonSchema,
+  path: string
+): Record<string, unknown> {
+  if (value === null || value === undefined) {
+    throw new SchemaValidationError(
+      `Expected object at ${path}, got ${value === null ? 'null' : 'undefined'}`,
+      path,
+      value
+    );
+  }
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    throw new SchemaValidationError(
+      `Expected object at ${path}, got ${typeof value}`,
+      path,
+      value
+    );
+  }
+
+  const obj = value as Record<string, unknown>;
+  const validated: Record<string, unknown> = {};
+
+  // Check required properties
+  if (schema.required) {
+    for (const req of schema.required) {
+      if (!(req in obj) || obj[req] === undefined) {
+        throw new SchemaValidationError(
+          `Missing required property '${req}' at ${path}`,
+          `${path}.${req}`,
+          undefined
+        );
+      }
+    }
+  }
+
+  // Validate and collect properties
+  const properties = schema.properties || {};
+  const seenKeys = new Set<string>();
+
+  for (const [key, val] of Object.entries(obj)) {
+    seenKeys.add(key);
+    const propSchema = properties[key];
+    if (propSchema) {
+      validated[key] = validateAgainstSchema(val, propSchema, `${path}.${key}`);
+    } else if (schema.additionalProperties === false) {
+      throw new SchemaValidationError(
+        `Unexpected property '${key}' at ${path} (additionalProperties is false)`,
+        `${path}.${key}`,
+        val
+      );
+    } else if (schema.additionalProperties && typeof schema.additionalProperties === 'object') {
+      validated[key] = validateAgainstSchema(
+        val,
+        schema.additionalProperties as JsonSchema,
+        `${path}.${key}`
+      );
+    } else {
+      validated[key] = val;
+    }
+  }
+
+  // Apply defaults for missing properties
+  for (const [key, propSchema] of Object.entries(properties)) {
+    if (!seenKeys.has(key) && propSchema.default !== undefined) {
+      validated[key] = propSchema.default;
+    }
+  }
+
+  return validated;
+}
+
+function validateArray(
+  value: unknown,
+  schema: JsonSchema,
+  path: string
+): unknown[] {
+  if (!Array.isArray(value)) {
+    throw new SchemaValidationError(
+      `Expected array at ${path}, got ${typeof value}`,
+      path,
+      value
+    );
+  }
+
+  if (schema.minItems !== undefined && value.length < schema.minItems) {
+    throw new SchemaValidationError(
+      `Array at ${path} has ${value.length} items, minimum is ${schema.minItems}`,
+      path,
+      value
+    );
+  }
+
+  if (schema.maxItems !== undefined && value.length > schema.maxItems) {
+    throw new SchemaValidationError(
+      `Array at ${path} has ${value.length} items, maximum is ${schema.maxItems}`,
+      path,
+      value
+    );
+  }
+
+  if (schema.items) {
+    return value.map((item, i) =>
+      validateAgainstSchema(item, schema.items!, `${path}[${i}]`)
+    );
+  }
+
+  return value;
+}
+
+function validateString(
+  value: unknown,
+  schema: JsonSchema,
+  path: string
+): string {
+  if (typeof value !== 'string') {
+    // Strict: no coercion from numbers/booleans
+    throw new SchemaValidationError(
+      `Expected string at ${path}, got ${typeof value}`,
+      path,
+      value
+    );
+  }
+
+  if (schema.minLength !== undefined && value.length < schema.minLength) {
+    throw new SchemaValidationError(
+      `String at ${path} is ${value.length} chars, minimum is ${schema.minLength}`,
+      path,
+      value
+    );
+  }
+
+  if (schema.maxLength !== undefined && value.length > schema.maxLength) {
+    throw new SchemaValidationError(
+      `String at ${path} is ${value.length} chars, maximum is ${schema.maxLength}`,
+      path,
+      value
+    );
+  }
+
+  if (schema.pattern && !new RegExp(schema.pattern).test(value)) {
+    throw new SchemaValidationError(
+      `String at ${path} does not match pattern '${schema.pattern}'`,
+      path,
+      value
+    );
+  }
+
+  if (schema.enum && !schema.enum.includes(value)) {
+    throw new SchemaValidationError(
+      `Value '${value}' at ${path} is not one of [${schema.enum.map(e => `'${e}'`).join(', ')}]`,
+      path,
+      value
+    );
+  }
+
+  return value;
+}
+
+function validateNumber(
+  value: unknown,
+  schema: JsonSchema,
+  path: string
+): number {
+  if (typeof value !== 'number' || Number.isNaN(value)) {
+    throw new SchemaValidationError(
+      `Expected number at ${path}, got ${typeof value}`,
+      path,
+      value
+    );
+  }
+
+  if (schema.type === 'integer' && !Number.isInteger(value)) {
+    throw new SchemaValidationError(
+      `Expected integer at ${path}, got float ${value}`,
+      path,
+      value
+    );
+  }
+
+  if (schema.minimum !== undefined && value < schema.minimum) {
+    throw new SchemaValidationError(
+      `Number ${value} at ${path} is below minimum ${schema.minimum}`,
+      path,
+      value
+    );
+  }
+
+  if (schema.maximum !== undefined && value > schema.maximum) {
+    throw new SchemaValidationError(
+      `Number ${value} at ${path} is above maximum ${schema.maximum}`,
+      path,
+      value
+    );
+  }
+
+  if (schema.enum && !schema.enum.includes(value)) {
+    throw new SchemaValidationError(
+      `Value ${value} at ${path} is not one of [${schema.enum.join(', ')}]`,
+      path,
+      value
+    );
+  }
+
+  return value;
+}
+
+function validateBoolean(
+  value: unknown,
+  schema: JsonSchema,
+  path: string
+): boolean {
+  if (typeof value !== 'boolean') {
+    throw new SchemaValidationError(
+      `Expected boolean at ${path}, got ${typeof value}`,
+      path,
+      value
+    );
+  }
+  return value;
+}

package/src/tools/types.ts

@@ -0,0 +1,104 @@
+/*
+ * File: types.ts
+ * Project: qwenproxy
+ * Tool system types
+ */
+
+/**
+ * JSON Schema definition following the OpenAI function calling spec.
+ */
+export interface JsonSchema {
+  type: string;
+  properties?: Record<string, JsonSchema>;
+  items?: JsonSchema;
+  required?: string[];
+  enum?: unknown[];
+  const?: unknown;
+  default?: unknown;
+  description?: string;
+  additionalProperties?: boolean | JsonSchema;
+  anyOf?: JsonSchema[];
+  oneOf?: JsonSchema[];
+  allOf?: JsonSchema[];
+  not?: JsonSchema;
+  if?: JsonSchema;
+  then?: JsonSchema;
+  else?: JsonSchema;
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  format?: string;
+  minItems?: number;
+  maxItems?: number;
+  uniqueItems?: boolean;
+  nullable?: boolean;
+}
+
+/**
+ * OpenAI-compatible function tool definition.
+ */
+export interface FunctionToolDefinition {
+  type: 'function';
+  function: {
+    name: string;
+    description?: string;
+    parameters?: JsonSchema;
+    strict?: boolean;
+  };
+}
+
+/**
+ * Internal tool registration entry.
+ */
+export interface ToolRegistration {
+  name: string;
+  description: string;
+  parameters: JsonSchema;
+  strict: boolean;
+  handler: ToolHandler;
+}
+
+/**
+ * Handler function signature for a registered tool.
+ * Receives the parsed and validated arguments.
+ * Returns the result as a string (or object that will be JSON-stringified).
+ */
+export type ToolHandler<TArgs = any, TResult = any> = (
+  args: TArgs,
+  context: ToolContext
+) => Promise<TResult>;
+
+/**
+ * Context passed to tool handlers during execution.
+ */
+export interface ToolContext {
+  /** The original messages from the request */
+  messages: unknown[];
+  /** The current turn number in the execution loop */
+  turn: number;
+  /** The model being used */
+  model: string;
+  /** Custom state or services can be attached here */
+  [key: string]: any;
+}
+
+/**
+ * A parsed tool call from the LLM response.
+ */
+export interface ParsedToolCall {
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+}
+
+/**
+ * Result of executing a single tool call.
+ */
+export interface ToolCallResult {
+  toolCallId: string;
+  name: string;
+  result: string;
+  isError: boolean;
+}

package/src/tools/validator.ts

@@ -0,0 +1,33 @@
+import Ajv from 'ajv';
+import type { ToolCallAST, ToolDefinition } from './ast.js';
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: any[] | null;
+  missingFields: string[];
+}
+
+export function validateToolCall(ast: ToolCallAST, toolDef: ToolDefinition): ValidationResult {
+  const validate = ajv.compile(toolDef.schema);
+  const valid = validate(ast.arguments);
+
+  const missingFields: string[] = [];
+  if (toolDef.schema && typeof toolDef.schema === 'object' && 'required' in toolDef.schema) {
+    const required = (toolDef.schema as any).required;
+    if (Array.isArray(required)) {
+      for (const field of required) {
+        if (!(ast.arguments && typeof ast.arguments === 'object' && field in (ast.arguments as Record<string, unknown>))) {
+          missingFields.push(field);
+        }
+      }
+    }
+  }
+
+  return {
+    valid,
+    errors: validate.errors ?? null,
+    missingFields,
+  };
+}

package/src/utils/context-truncation.ts

@@ -0,0 +1,61 @@
+export interface TruncatedMessage {
+  role: string;
+  content: string;
+}
+
+export function estimateTokenCount(text: string): number {
+  return Math.ceil(text.length / 3.5);
+}
+
+export function truncateMessages(
+  messages: Array<{ role: string; content: string | null | any[] }>,
+  maxContextLength: number,
+  systemPrompt: string = ''
+): Array<{ role: string; content: string }> {
+  const systemTokens = estimateTokenCount(systemPrompt);
+  const availableTokens = maxContextLength - systemTokens - 500;
+  
+  if (availableTokens <= 0) {
+    return [{ role: 'user', content: systemPrompt }];
+  }
+  
+  const result: Array<{ role: string; content: string }> = [];
+  let usedTokens = 0;
+  
+  const normalizedMessages = messages.map(msg => {
+    let contentStr = '';
+    if (Array.isArray(msg.content)) {
+      contentStr = msg.content.map((c: any) => c.text || JSON.stringify(c)).join('\n');
+    } else if (typeof msg.content === 'object' && msg.content !== null) {
+      contentStr = JSON.stringify(msg.content);
+    } else {
+      contentStr = msg.content || '';
+    }
+    return { role: msg.role, content: contentStr };
+  });
+  
+  for (let i = normalizedMessages.length - 1; i >= 0; i--) {
+    const msg = normalizedMessages[i];
+    const msgTokens = estimateTokenCount(msg.content);
+    
+    if (usedTokens + msgTokens <= availableTokens) {
+      result.unshift(msg);
+      usedTokens += msgTokens;
+    } else {
+      const remainingTokens = availableTokens - usedTokens;
+      if (remainingTokens > 100) {
+        const truncatedContent = msg.content.slice(0, remainingTokens * 3.5);
+        result.unshift({ role: msg.role, content: `[Truncated] ${truncatedContent}...` });
+      }
+      break;
+    }
+  }
+  
+  if (result.length === 0 && normalizedMessages.length > 0) {
+    const lastMsg = normalizedMessages[normalizedMessages.length - 1];
+    const truncatedContent = lastMsg.content.slice(0, Math.max(200, availableTokens * 3.5));
+    result.push({ role: lastMsg.role, content: `[Truncated] ${truncatedContent}...` });
+  }
+  
+  return result;
+}