oricore 1.2.0 → 1.3.0

package/README.md

@@ -51,6 +51,16 @@ pnpm add oricore
 bun add oricore
 ```
 
+### Optional Dependencies
+
+OriCore has support for additional features through optional dependencies:
+
+**PDF Support**
+```bash
+npm install pdf-parse
+```
+The `read` tool can parse PDF files when `pdf-parse` is installed. Without it, PDF reading will be disabled.
+
 ## Quick Start
 
 ```typescript
@@ -113,7 +123,7 @@ OriCore includes a comprehensive set of tools:
 
 | Tool | Description |
 |------|-------------|
-| `read` | Read file contents |
+| `read` | Read file contents (supports text, images, and PDF*) |
 | `write` | Write new files |
 | `edit` | Edit existing files with search/replace |
 | `glob` | Find files by pattern |
@@ -124,6 +134,8 @@ OriCore includes a comprehensive set of tools:
 | `task` | Spawn specialized agents |
 | `todo` | Track task progress |
 
+*PDF support requires the optional `pdf-parse` package (see below)
+
 ## Configuration
 
 ### Full Configuration Example

package/README.zh-CN.md

@@ -51,6 +51,16 @@ pnpm add oricore
 bun add oricore
 ```
 
+### 可选依赖
+
+OriCore 支持通过可选依赖来扩展功能：
+
+**PDF 支持**
+```bash
+npm install pdf-parse
+```
+安装 `pdf-parse` 后，`read` 工具可以解析 PDF 文件。未安装时，PDF 读取功能将被禁用。
+
 ## 快速开始
 
 ```typescript
@@ -113,7 +123,7 @@ OriCore 包含一套完整的工具：
 
 | 工具 | 描述 |
 |------|------|
-| `read` | 读取文件内容 |
+| `read` | 读取文件内容（支持文本、图片和 PDF*） |
 | `write` | 写入新文件 |
 | `edit` | 编辑现有文件（搜索/替换） |
 | `glob` | 按模式查找文件 |
@@ -124,6 +134,8 @@ OriCore 包含一套完整的工具：
 | `task` | 启动专用 Agent |
 | `todo` | 跟踪任务进度 |
 
+*PDF 支持需要安装可选的 `pdf-parse` 包（见上文）
+
 ## 配置
 
 ### 完整配置示例

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oricore",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "OriCore - A powerful AI engine with multi-modal support, tool calling, and extensible architecture",
   "type": "module",
   "main": "./dist/index.js",

package/src/core/config.ts

@@ -3,6 +3,12 @@ import fs from 'fs';
 import { homedir } from 'os';
 import path from 'pathe';
 import type { Provider } from '../core/model';
+import {
+  assertValidConfig,
+  formatValidationErrors,
+  type ValidationResult,
+  validateConfig,
+} from './configValidation';
 
 export type McpStdioServerConfig = {
   type: 'stdio';
@@ -167,6 +173,7 @@ export class ConfigManager {
   argvConfig: Partial<Config>;
   globalConfigPath: string;
   projectConfigPath: string;
+  private validationEnabled: boolean = false;
 
   constructor(cwd: string, productName: string, argvConfig: Partial<Config>) {
     const lowerProductName = productName.toLowerCase();
@@ -203,9 +210,57 @@ export class ConfigManager {
     config.planModel = config.planModel || config.model;
     config.smallModel = config.smallModel || config.model;
     config.visionModel = config.visionModel || config.model;
+
+    // Validate config if enabled
+    if (this.validationEnabled) {
+      assertValidConfig(config);
+    }
+
     return config;
   }
 
+  /**
+   * Enable configuration validation
+   * When enabled, invalid configurations will throw errors
+   */
+  enableValidation(): void {
+    this.validationEnabled = true;
+  }
+
+  /**
+   * Disable configuration validation
+   */
+  disableValidation(): void {
+    this.validationEnabled = false;
+  }
+
+  /**
+   * Validate the current configuration
+   * Returns validation result without throwing
+   */
+  validate(): ValidationResult {
+    const config = defu(
+      this.argvConfig,
+      defu(this.projectConfig, defu(this.globalConfig, DEFAULT_CONFIG)),
+    ) as Config;
+    config.planModel = config.planModel || config.model;
+    config.smallModel = config.smallModel || config.model;
+    config.visionModel = config.visionModel || config.model;
+
+    return validateConfig(config);
+  }
+
+  /**
+   * Get validation errors as a formatted string
+   */
+  getValidationErrors(): string {
+    const result = this.validate();
+    if (result.valid) {
+      return 'Configuration is valid';
+    }
+    return formatValidationErrors(result);
+  }
+
   removeConfig(global: boolean, key: string, values?: string[]) {
     assertGlobalAllowed(global, key);
     const config = global ? this.globalConfig : this.projectConfig;

package/src/core/configValidation.ts

@@ -0,0 +1,293 @@
+/**
+ * Configuration Validation
+ * Runtime validation for engine configuration
+ */
+
+import type { Config, McpServerConfig } from './config';
+import { z } from 'zod';
+
+/**
+ * Validation result
+ */
+export interface ValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+  warnings: ValidationWarning[];
+}
+
+export interface ValidationError {
+  path: string;
+  message: string;
+  value?: any;
+}
+
+export interface ValidationWarning {
+  path: string;
+  message: string;
+  value?: any;
+}
+
+/**
+ * MCP server configuration schema
+ */
+const McpServerConfigSchema = z.object({
+  type: z.enum(['stdio', 'sse', 'http']).optional(),
+  command: z.string().optional(),
+  args: z.array(z.string()).optional(),
+  env: z.record(z.string(), z.string()).optional(),
+  url: z.string().optional(),
+  disable: z.boolean().optional(),
+  timeout: z.number().positive().optional(),
+  headers: z.record(z.string(), z.string()).optional(),
+});
+
+/**
+ * Provider configuration schema
+ */
+const ProviderConfigSchema = z.object({
+  apiKey: z.string().optional(),
+  apiKeys: z.array(z.string()).optional(),
+  baseURL: z.string().optional(),
+  proxy: z.string().optional(),
+});
+
+/**
+ * Agent configuration schema
+ */
+const AgentConfigSchema = z.object({
+  model: z.string().optional(),
+  tools: z.array(z.string()).optional(),
+  disallowedTools: z.array(z.string()).optional(),
+  forkContext: z.boolean().optional(),
+  color: z.string().optional(),
+});
+
+/**
+ * Main configuration schema
+ */
+const ConfigSchema = z.object({
+  // Model configuration
+  model: z.string().min(1, 'Model cannot be empty'),
+  planModel: z.string().optional(),
+  smallModel: z.string().optional(),
+  visionModel: z.string().optional(),
+
+  // Behavior configuration
+  language: z.string().optional(),
+  quiet: z.boolean().optional(),
+  approvalMode: z.enum(['default', 'autoEdit', 'yolo']).optional(),
+  autoCompact: z.boolean().optional(),
+  temperature: z
+    .number()
+    .min(0, 'Temperature must be at least 0')
+    .max(2, 'Temperature must be at most 2')
+    .optional(),
+
+  // Feature flags
+  plugins: z.array(z.string()).optional(),
+  tools: z.record(z.string(), z.boolean()).optional(),
+  todo: z.boolean().optional(),
+
+  // MCP servers
+  mcpServers: z.record(z.string(), z.any()).optional(), // Validated separately
+
+  // Provider extensions
+  provider: z.record(z.string(), z.any()).optional(), // Validated separately
+
+  // Extensions
+  extensions: z.record(z.string(), z.any()).optional(),
+
+  // Agents
+  agent: z.record(z.string(), z.any()).optional(), // Validated separately
+});
+
+/**
+ * Validate a configuration object
+ */
+export function validateConfig(config: Partial<Config>): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  // Validate main config structure
+  const mainResult = ConfigSchema.safeParse(config);
+  if (!mainResult.success) {
+    for (const issue of mainResult.error.issues) {
+      errors.push({
+        path: issue.path.join('.'),
+        message: issue.message,
+        value: getNestedValue(config, issue.path as (string | number)[]),
+      });
+    }
+  }
+
+  // Validate MCP servers if present
+  if (config.mcpServers) {
+    for (const [name, mcpConfig] of Object.entries(config.mcpServers)) {
+      const mcpResult = McpServerConfigSchema.safeParse(mcpConfig);
+      if (!mcpResult.success) {
+        for (const issue of mcpResult.error.issues) {
+          errors.push({
+            path: `mcpServers.${name}.${issue.path.join('.')}`,
+            message: issue.message,
+            value: getNestedValue(mcpConfig, issue.path as (string | number)[]),
+          });
+        }
+      }
+
+      // Additional validation: MCP server must have either command or url
+      const mcp = mcpConfig as any;
+      if (!mcp.disable && !mcp.command && !mcp.url) {
+        errors.push({
+          path: `mcpServers.${name}`,
+          message: 'MCP server must have either "command" or "url" configured',
+          value: mcp,
+        });
+      }
+
+      // Warning: stdio type requires command
+      if (mcp.type === 'stdio' && !mcp.command) {
+        warnings.push({
+          path: `mcpServers.${name}`,
+          message: 'stdio MCP server type requires "command" to be set',
+          value: mcp,
+        });
+      }
+
+      // Warning: http/sse type requires url
+      if ((mcp.type === 'http' || mcp.type === 'sse') && !mcp.url) {
+        warnings.push({
+          path: `mcpServers.${name}`,
+          message: `${mcp.type} MCP server type requires "url" to be set`,
+          value: mcp,
+        });
+      }
+    }
+  }
+
+  // Validate provider configs if present
+  if (config.provider) {
+    for (const [name, providerConfig] of Object.entries(config.provider)) {
+      const providerResult = ProviderConfigSchema.safeParse(providerConfig);
+      if (!providerResult.success) {
+        for (const issue of providerResult.error.issues) {
+          errors.push({
+            path: `provider.${name}.${issue.path.join('.')}`,
+            message: issue.message,
+            value: getNestedValue(providerConfig, issue.path as (string | number)[]),
+          });
+        }
+      }
+
+      // Warning: Multiple API keys detected but no apiKey (single)
+      const provider = providerConfig as any;
+      if (provider.apiKeys && provider.apiKeys.length > 1 && !provider.apiKey) {
+        warnings.push({
+          path: `provider.${name}`,
+          message: 'Multiple API keys detected - rotation will be used',
+          value: { apiKeyCount: provider.apiKeys.length },
+        });
+      }
+    }
+  }
+
+  // Validate agent configs if present
+  if (config.agent) {
+    for (const [name, agentConfig] of Object.entries(config.agent)) {
+      const agentResult = AgentConfigSchema.safeParse(agentConfig);
+      if (!agentResult.success) {
+        for (const issue of agentResult.error.issues) {
+          errors.push({
+            path: `agent.${name}.${issue.path.join('.')}`,
+            message: issue.message,
+            value: getNestedValue(agentConfig, issue.path as (string | number)[]),
+          });
+        }
+      }
+    }
+  }
+
+  // Validate temperature range
+  if (config.temperature !== undefined) {
+    if (config.temperature < 0 || config.temperature > 2) {
+      errors.push({
+        path: 'temperature',
+        message: 'Temperature must be between 0 and 2',
+        value: config.temperature,
+      });
+    }
+  }
+
+  // Validate language code format
+  if (config.language) {
+    const languageCodeRegex = /^[a-z]{2}(-[A-Z]{2})?$/;
+    if (!languageCodeRegex.test(config.language)) {
+      warnings.push({
+        path: 'language',
+        message: 'Language code should be in ISO 639-1 format (e.g., "en", "zh-CN")',
+        value: config.language,
+      });
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Get nested value from object using path array
+ */
+function getNestedValue(obj: any, path: (string | number)[]): any {
+  let current = obj;
+  for (const key of path) {
+    if (current == null) {
+      return undefined;
+    }
+    current = current[key];
+  }
+  return current;
+}
+
+/**
+ * Format validation errors for display
+ */
+export function formatValidationErrors(result: ValidationResult): string {
+  const lines: string[] = [];
+
+  if (result.errors.length > 0) {
+    lines.push('Configuration errors:');
+    for (const error of result.errors) {
+      const valueStr =
+        error.value !== undefined ? ` (got: ${JSON.stringify(error.value)})` : '';
+      lines.push(`  - ${error.path}: ${error.message}${valueStr}`);
+    }
+  }
+
+  if (result.warnings.length > 0) {
+    if (lines.length > 0) lines.push('');
+    lines.push('Configuration warnings:');
+    for (const warning of result.warnings) {
+      const valueStr =
+        warning.value !== undefined
+          ? ` (value: ${JSON.stringify(warning.value)})`
+          : '';
+      lines.push(`  - ${warning.path}: ${warning.message}${valueStr}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Assert that configuration is valid, throws if not
+ */
+export function assertValidConfig(config: Partial<Config>): void {
+  const result = validateConfig(config);
+  if (!result.valid) {
+    throw new Error(
+      `Invalid configuration:\n${formatValidationErrors(result)}`,
+    );
+  }
+}

package/src/core/history.ts

@@ -295,12 +295,52 @@ export class History {
       });
     } catch (error) {
       debug('Compact failed:', error);
-      throw new Error(
-        `History compaction failed: ${error instanceof Error ? error.message : String(error)}`,
-      );
+
+      // Graceful degradation: instead of throwing, use a simple summary
+      const fallbackSummary = this.#generateFallbackSummary();
+      debug('Using fallback summary due to compaction failure');
+
+      const summaryMessage: NormalizedMessage = {
+        parentUuid: null,
+        uuid: randomUUID(),
+        role: 'user',
+        content: [{ type: 'text', text: fallbackSummary }],
+        uiContent: COMPACT_MESSAGE,
+        type: 'message',
+        timestamp: new Date().toISOString(),
+      };
+      this.messages = [summaryMessage];
+      await this.onMessage?.(summaryMessage);
+
+      return {
+        compressed: true,
+        summary: fallbackSummary,
+        fallback: true,
+        error: error instanceof Error ? error.message : String(error),
+      };
     }
     if (!summary || summary.trim().length === 0) {
-      throw new Error('Generated summary is empty');
+      // If summary is empty, use fallback
+      const fallbackSummary = this.#generateFallbackSummary();
+      debug('Generated summary is empty, using fallback');
+
+      const summaryMessage: NormalizedMessage = {
+        parentUuid: null,
+        uuid: randomUUID(),
+        role: 'user',
+        content: [{ type: 'text', text: fallbackSummary }],
+        uiContent: COMPACT_MESSAGE,
+        type: 'message',
+        timestamp: new Date().toISOString(),
+      };
+      this.messages = [summaryMessage];
+      await this.onMessage?.(summaryMessage);
+
+      return {
+        compressed: true,
+        summary: fallbackSummary,
+        fallback: true,
+      };
     }
 
     const summaryMessage: NormalizedMessage = {
@@ -318,6 +358,65 @@ export class History {
     return {
       compressed: true,
       summary,
+      fallback: false,
     };
   }
+
+  /**
+   * Generate a simple fallback summary when AI compression fails
+   * This ensures the conversation can continue even if compression fails
+   */
+  #generateFallbackSummary(): string {
+    const messageCount = this.messages.length;
+    const lastUserMessage = [...this.messages]
+      .reverse()
+      .find((m) => m.role === 'user');
+
+    const recentTools = new Set<string>();
+    for (let i = this.messages.length - 1; i >= 0 && recentTools.size < 5; i--) {
+      const msg = this.messages[i];
+      if (msg.role === 'tool') {
+        for (const part of msg.content as any[]) {
+          if (part.type === 'tool-result') {
+            recentTools.add(part.toolName);
+          }
+        }
+      }
+    }
+
+    const sections: string[] = [];
+
+    sections.push(`<conversation_overview>`);
+    sections.push(
+      `Previous conversation contained ${messageCount} messages. `,
+    );
+    if (lastUserMessage) {
+      const content =
+        typeof lastUserMessage.content === 'string'
+          ? lastUserMessage.content
+          : JSON.stringify(lastUserMessage.content);
+      const preview =
+        content.length > 100
+          ? content.substring(0, 100) + '...'
+          : content;
+      sections.push(`Last user message was about: "${preview}"`);
+    }
+    sections.push(`</conversation_overview>`);
+
+    if (recentTools.size > 0) {
+      sections.push(`\n<recent_actions>`);
+      sections.push(`Recent tools used: ${Array.from(recentTools).join(', ')}`);
+      sections.push(`</recent_actions>`);
+    }
+
+    sections.push(`\n<note>`);
+    sections.push(
+      `This is an auto-generated summary due to compression unavailability. `,
+    );
+    sections.push(`The conversation history has been compressed to continue the session. `,
+    );
+    sections.push(`</note>`);
+
+    return sections.join('\n');
+  }
 }

package/src/session/session.ts

@@ -5,6 +5,8 @@ import { History } from '../core/history';
 import type { NormalizedMessage } from '../core/message';
 import { Usage } from '../core/usage';
 import { randomUUID } from '../utils/randomUUID';
+import { lockRegistry } from '../utils/fileLock';
+import type { ModeType } from '../modes/types';
 
 export type SessionId = string;
 
@@ -65,8 +67,10 @@ const DEFAULT_SESSION_CONFIG: SessionConfig = {
 export class SessionConfigManager {
   logPath: string;
   config: SessionConfig;
+  mode: ModeType | null;
   constructor(opts: { logPath: string }) {
     this.logPath = opts.logPath;
+    this.mode = null;
     this.config = this.load(opts.logPath);
   }
 
@@ -81,6 +85,10 @@ export class SessionConfigManager {
         try {
           const parsed = JSON.parse(line);
           if (parsed.type === 'config') {
+            // Load mode if present
+            if (parsed.mode) {
+              this.mode = parsed.mode;
+            }
             return parsed.config;
           }
         } catch {}
@@ -90,33 +98,49 @@ export class SessionConfigManager {
       return DEFAULT_SESSION_CONFIG;
     }
   }
-  write() {
-    // TODO: add write lock
-    const configLine = JSON.stringify({ type: 'config', config: this.config });
-    if (!fs.existsSync(this.logPath)) {
-      fs.mkdirSync(path.dirname(this.logPath), { recursive: true });
-      fs.writeFileSync(this.logPath, configLine + '\n', 'utf-8');
-      return;
-    }
-    try {
-      const content = fs.readFileSync(this.logPath, 'utf-8');
-      const lines = content.split('\n');
-      const filteredLines = lines.filter((line) => {
-        if (!line) return false;
-        try {
-          const parsed = JSON.parse(line);
-          return parsed.type !== 'config';
-        } catch {
-          return true;
-        }
+
+  setMode(mode: ModeType): void {
+    this.mode = mode;
+  }
+
+  getMode(): ModeType | null {
+    return this.mode;
+  }
+
+  async write() {
+    const lock = lockRegistry.getLock(this.logPath);
+
+    await lock.withLock(async () => {
+      const configLine = JSON.stringify({
+        type: 'config',
+        config: this.config,
+        mode: this.mode,
       });
-      const newContent = [configLine, ...filteredLines].join('\n');
-      fs.writeFileSync(this.logPath, newContent + '\n', 'utf-8');
-    } catch (e: any) {
-      throw new Error(
-        `Failed to write config to log file: ${this.logPath}: ${e.message}`,
-      );
-    }
+      if (!fs.existsSync(this.logPath)) {
+        fs.mkdirSync(path.dirname(this.logPath), { recursive: true });
+        fs.writeFileSync(this.logPath, configLine + '\n', 'utf-8');
+        return;
+      }
+      try {
+        const content = fs.readFileSync(this.logPath, 'utf-8');
+        const lines = content.split('\n');
+        const filteredLines = lines.filter((line) => {
+          if (!line) return false;
+          try {
+            const parsed = JSON.parse(line);
+            return parsed.type !== 'config';
+          } catch {
+            return true;
+          }
+        });
+        const newContent = [configLine, ...filteredLines].join('\n');
+        fs.writeFileSync(this.logPath, newContent + '\n', 'utf-8');
+      } catch (e: any) {
+        throw new Error(
+          `Failed to write config to log file: ${this.logPath}: ${e.message}`,
+        );
+      }
+    });
   }
 }
 

package/src/tools/tools/read.ts

@@ -9,6 +9,11 @@ import {
   MaxFileReadTokenExceededError,
 } from '../../utils/error';
 import { safeStringify } from '../../utils/safeStringify';
+import {
+  formatPDFResult,
+  isPDFParsingAvailable,
+  parsePDF,
+} from '../../utils/pdf-parser';
 
 type ImageMediaType =
   | 'image/jpeg'
@@ -136,11 +141,6 @@ Usage:
 
         const ext = path.extname(file_path).toLowerCase();
 
-        // Handle PDF files
-        if ('.pdf' === ext) {
-          throw new Error('PDF files are not supported yet');
-        }
-
         const fullFilePath = (() => {
           if (path.isAbsolute(file_path)) {
             return file_path;
@@ -158,6 +158,69 @@ Usage:
           throw new Error(`File ${file_path} does not exist.`);
         })();
 
+        // Handle PDF files
+        if ('.pdf' === ext) {
+          const pdfAvailable = await isPDFParsingAvailable();
+          if (!pdfAvailable) {
+            throw new Error(
+              'PDF parsing requires the "pdf-parse" package. Install it with: npm install pdf-parse',
+            );
+          }
+
+          const stats = fs.statSync(fullFilePath);
+
+          // Security: Validate file path to prevent traversal attacks
+          const resolvedPath = path.resolve(fullFilePath);
+          const normalizedCwd = path.resolve(opts.cwd);
+          if (!resolvedPath.startsWith(normalizedCwd)) {
+            throw new Error('Invalid file path: path traversal detected');
+          }
+
+          // Check file size (warn if > 5MB)
+          const fileSizeMB = stats.size / (1024 * 1024);
+          if (fileSizeMB > 5) {
+            return {
+              isError: true,
+              llmContent: `PDF file is too large (${Math.round(fileSizeMB * 100) / 100}MB). Maximum supported size is 5MB for PDF files.`,
+            };
+          }
+
+          try {
+            const result = await parsePDF(fullFilePath, {
+              maxPages: 100, // Limit to 100 pages
+              maxCharsPerPage: 5000, // Limit per page
+              includeMetadata: true,
+            });
+
+            // Check token count
+            const tokenCount = countTokens(result.text);
+            const MAX_PDF_TOKENS = 15000;
+            if (tokenCount > MAX_PDF_TOKENS) {
+              return {
+                isError: true,
+                llmContent: `PDF content is too large (${tokenCount} tokens). Maximum supported is ${MAX_PDF_TOKENS} tokens. Try extracting specific pages.`,
+              };
+            }
+
+            return {
+              returnDisplay: `Read PDF file (${result.pageCount} pages)`,
+              llmContent: safeStringify({
+                type: 'pdf',
+                filePath: file_path,
+                pageCount: result.pageCount,
+                metadata: result.metadata,
+                content: result.text,
+                tokenCount,
+              }),
+            };
+          } catch (error) {
+            return {
+              isError: true,
+              llmContent: `Failed to parse PDF file: ${error instanceof Error ? error.message : String(error)}`,
+            };
+          }
+        }
+
         // Handle image files
         if (IMAGE_EXTENSIONS.has(ext)) {
           const result = await processImage(fullFilePath, opts.cwd);

package/src/types/pdf-parse.d.ts

@@ -0,0 +1,22 @@
+declare module 'pdf-parse' {
+  interface PDFParseOptions {
+    max?: number;
+  }
+
+  interface PDFParseData {
+    numpages: number;
+    numrender: number;
+    info: any;
+    metadata: any;
+    text: string;
+    version: string;
+  }
+
+  interface PDFStatic {
+    (buffer: Buffer, options?: PDFParseOptions): Promise<PDFParseData>;
+    default: (buffer: Buffer, options?: PDFParseOptions) => Promise<PDFParseData>;
+  }
+
+  const pdfParse: PDFStatic;
+  export = pdfParse;
+}

package/src/utils/fileLock.ts

@@ -0,0 +1,191 @@
+import fs from 'fs';
+import path from 'pathe';
+import { randomUUID } from './randomUUID';
+
+const LOCK_TIMEOUT = 30_000; // 30 seconds
+const LOCK_POLL_INTERVAL = 100; // 100ms
+
+/**
+ * File-based lock for concurrent write safety
+ * Uses lock files with unique identifiers to prevent race conditions
+ */
+export class FileLock {
+  private lockFilePath: string;
+  private lockId: string | null = null;
+  private acquired = false;
+
+  constructor(filePath: string) {
+    // Lock file is the original file path with .lock extension
+    this.lockFilePath = `${filePath}.lock`;
+  }
+
+  /**
+   * Attempt to acquire the lock
+   * @returns true if lock was acquired, false otherwise
+   */
+  async acquire(): Promise<boolean> {
+    const startTime = Date.now();
+
+    while (Date.now() - startTime < LOCK_TIMEOUT) {
+      try {
+        // Try to create lock file exclusively
+        const lockId = randomUUID();
+        const lockContent = JSON.stringify({
+          lockId,
+          pid: process.pid,
+          timestamp: Date.now(),
+        });
+
+        // Check if lock file exists and is valid
+        if (fs.existsSync(this.lockFilePath)) {
+          const existingLock = this.readLockFile();
+          if (existingLock && !this.isLockExpired(existingLock)) {
+            // Lock is held by another process and not expired
+            await new Promise((resolve) =>
+              setTimeout(resolve, LOCK_POLL_INTERVAL),
+            );
+            continue;
+          }
+          // Lock is expired or invalid, try to remove it
+          try {
+            fs.unlinkSync(this.lockFilePath);
+          } catch {
+            // Ignore errors, another process might have removed it
+          }
+        }
+
+        // Try to create lock file atomically
+        fs.writeFileSync(this.lockFilePath, lockContent, {
+          flag: 'wx', // Exclusive create (fail if exists)
+        });
+
+        this.lockId = lockId;
+        this.acquired = true;
+        return true;
+      } catch (error: any) {
+        if (error.code === 'EEXIST') {
+          // Lock file exists, wait and retry
+          await new Promise((resolve) =>
+            setTimeout(resolve, LOCK_POLL_INTERVAL),
+          );
+          continue;
+        }
+        // Other error, fail fast
+        return false;
+      }
+    }
+
+    // Timeout exceeded
+    return false;
+  }
+
+  /**
+   * Release the lock
+   * Only releases if this instance holds the lock (matching lockId)
+   */
+  release(): void {
+    if (!this.acquired || !this.lockId) {
+      return;
+    }
+
+    try {
+      const existingLock = this.readLockFile();
+      if (existingLock && existingLock.lockId === this.lockId) {
+        fs.unlinkSync(this.lockFilePath);
+      }
+    } catch {
+      // Ignore errors during release
+    } finally {
+      this.acquired = false;
+      this.lockId = null;
+    }
+  }
+
+  /**
+   * Execute a callback while holding the lock
+   * Automatically acquires and releases the lock
+   */
+  async withLock<T>(callback: () => T | Promise<T>): Promise<T> {
+    const acquired = await this.acquire();
+    if (!acquired) {
+      throw new Error(
+        `Failed to acquire lock for ${this.lockFilePath} after ${LOCK_TIMEOUT}ms`,
+      );
+    }
+
+    try {
+      return await callback();
+    } finally {
+      this.release();
+    }
+  }
+
+  /**
+   * Read and parse the lock file
+   */
+  private readLockFile():
+    | { lockId: string; pid: number; timestamp: number }
+    | null {
+    try {
+      const content = fs.readFileSync(this.lockFilePath, 'utf-8');
+      return JSON.parse(content);
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Check if a lock has expired (older than timeout)
+   */
+  private isLockExpired(lock: {
+    lockId: string;
+    pid: number;
+    timestamp: number;
+  }): boolean {
+    return Date.now() - lock.timestamp > LOCK_TIMEOUT;
+  }
+
+  /**
+   * Force release any existing lock (use with caution)
+   * This can be used to recover from stale locks
+   */
+  forceRelease(): void {
+    try {
+      if (fs.existsSync(this.lockFilePath)) {
+        fs.unlinkSync(this.lockFilePath);
+      }
+    } catch {
+      // Ignore errors
+    }
+  }
+}
+
+/**
+ * Global lock registry to manage multiple locks
+ * Helps prevent deadlocks and track active locks
+ */
+class LockRegistry {
+  private locks = new Map<string, FileLock>();
+
+  /**
+   * Get or create a lock for a file path
+   */
+  getLock(filePath: string): FileLock {
+    if (!this.locks.has(filePath)) {
+      this.locks.set(filePath, new FileLock(filePath));
+    }
+    return this.locks.get(filePath)!;
+  }
+
+  /**
+   * Release all locks (useful for cleanup)
+   */
+  releaseAll(): void {
+    for (const lock of this.locks.values()) {
+      lock.release();
+    }
+    this.locks.clear();
+  }
+}
+
+export const lockRegistry = new LockRegistry();

package/src/utils/pdf-parser.ts

@@ -0,0 +1,186 @@
+/**
+ * PDF Parser Utility
+ * Extracts text content from PDF files
+ */
+
+import fs from 'fs';
+import path from 'pathe';
+
+export interface ParseResult {
+  text: string;
+  pageCount: number;
+  metadata?: {
+    title?: string;
+    author?: string;
+    subject?: string;
+    keywords?: string;
+    creator?: string;
+    producer?: string;
+    creationDate?: string;
+    modificationDate?: string;
+  };
+}
+
+export interface ParseOptions {
+  /**
+   * Maximum number of pages to parse (0 = all pages)
+   * @default 0
+   */
+  maxPages?: number;
+
+  /**
+   * Maximum text length per page (0 = no limit)
+   * @default 10000
+   */
+  maxCharsPerPage?: number;
+
+  /**
+   * Include metadata in the result
+   * @default true
+   */
+  includeMetadata?: boolean;
+}
+
+const DEFAULT_OPTIONS: ParseOptions = {
+  maxPages: 0, // Parse all pages
+  maxCharsPerPage: 10000,
+  includeMetadata: true,
+};
+
+/**
+ * Parse a PDF file and extract text content
+ *
+ * @param filePath - Absolute path to the PDF file
+ * @param options - Parsing options
+ * @returns Parsed PDF content
+ */
+export async function parsePDF(
+  filePath: string,
+  options: ParseOptions = {},
+): Promise<ParseResult> {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+
+  // Validate file exists
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`PDF file not found: ${filePath}`);
+  }
+
+  // Get file stats
+  const stats = fs.statSync(filePath);
+  const fileSizeMB = stats.size / (1024 * 1024);
+
+  // Check file size (warn if > 10MB)
+  if (fileSizeMB > 10) {
+    console.warn(
+      `PDF file is large (${fileSizeMB.toFixed(2)}MB), parsing may take a while`,
+    );
+  }
+
+  try {
+    // Try to use pdf-parse if available
+    const pdfParse = await import('pdf-parse');
+    const dataBuffer = fs.readFileSync(filePath);
+
+    const data = await pdfParse.default(dataBuffer, {
+      // Only parse requested pages
+      max: opts.maxPages || undefined,
+    });
+
+    // Truncate text per page if needed
+    let text = data.text;
+    if (opts.maxCharsPerPage && opts.maxCharsPerPage > 0) {
+      // Split by pages (pdf-parse doesn't give page breaks, so we split by heuristics)
+      // This is a simple approach - for better results, use a library that preserves page structure
+      text = text
+        .split(/\f/) // Form feed character often used as page separator
+        .map((pageText: string) => {
+          if (pageText.length > opts.maxCharsPerPage!) {
+            return pageText.substring(0, opts.maxCharsPerPage) + '... [truncated]';
+          }
+          return pageText;
+        })
+        .join('\n\n--- Page Break ---\n\n');
+    }
+
+    const result: ParseResult = {
+      text: text.trim(),
+      pageCount: data.numpages,
+    };
+
+    // Add metadata if requested and available
+    if (opts.includeMetadata) {
+      const metadata: ParseResult['metadata'] = {};
+
+      if (data.info) {
+        if (data.info.Title) metadata.title = String(data.info.Title);
+        if (data.info.Author) metadata.author = String(data.info.Author);
+        if (data.info.Subject) metadata.subject = String(data.info.Subject);
+        if (data.info.Keywords) metadata.keywords = String(data.info.Keywords);
+        if (data.info.Creator) metadata.creator = String(data.info.Creator);
+        if (data.info.Producer) metadata.producer = String(data.info.Producer);
+        if (data.info.CreationDate)
+          metadata.creationDate = String(data.info.CreationDate);
+        if (data.info.ModDate)
+          metadata.modificationDate = String(data.info.ModDate);
+      }
+
+      if (Object.keys(metadata).length > 0) {
+        result.metadata = metadata;
+      }
+    }
+
+    return result;
+  } catch (error: any) {
+    if (error.code === 'MODULE_NOT_FOUND' || error.code === 'ERR_MODULE_NOT_FOUND') {
+      // pdf-parse not available, provide helpful error
+      throw new Error(
+        'PDF parsing requires the "pdf-parse" package. Install it with: npm install pdf-parse',
+      );
+    }
+
+    throw new Error(
+      `Failed to parse PDF file: ${error.message || String(error)}`,
+    );
+  }
+}
+
+/**
+ * Check if PDF parsing is available (pdf-parse is installed)
+ */
+export async function isPDFParsingAvailable(): Promise<boolean> {
+  try {
+    await import('pdf-parse');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Format PDF parse result for LLM consumption
+ */
+export function formatPDFResult(result: ParseResult): string {
+  const sections: string[] = [];
+
+  sections.push(`# PDF Document`);
+  sections.push(`Pages: ${result.pageCount}`);
+
+  if (result.metadata) {
+    const meta: string[] = [];
+    if (result.metadata.title) meta.push(`Title: ${result.metadata.title}`);
+    if (result.metadata.author) meta.push(`Author: ${result.metadata.author}`);
+    if (result.metadata.subject) meta.push(`Subject: ${result.metadata.subject}`);
+    if (result.metadata.creationDate)
+      meta.push(`Created: ${result.metadata.creationDate}`);
+
+    if (meta.length > 0) {
+      sections.push('\n## Metadata');
+      sections.push(meta.join('\n'));
+    }
+  }
+
+  sections.push('\n## Content');
+  sections.push(result.text);
+
+  return sections.join('\n');
+}