Tools & Function Calling

// Documentation check: complete example
import { type ToolFunction } from 'oneringai';

const weatherTool: ToolFunction = {
  definition: {
    type: 'function',
    function: {
      name: 'get_weather',
      description: 'Get current weather for a location',
      parameters: {
        type: 'object',
        properties: {
          location: {
            type: 'string',
            description: 'City name, e.g., "San Francisco"',
          },
          units: {
            type: 'string',
            enum: ['celsius', 'fahrenheit'],
            description: 'Temperature units',
          },
        },
        required: ['location'],
      },
    },
  },
  execute: async (args) => {
    // Your implementation
    const { location, units = 'fahrenheit' } = args;

    // Call weather API
    const temp = 72; // Example

    return {
      location,
      temperature: temp,
      units,
      conditions: 'sunny',
    };
  },
};

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: [weatherTool, calculatorTool, searchTool],
});

const response = await agent.run('What is the weather in Paris?');

// Agent will:
// 1. Recognize it needs weather data
// 2. Call weatherTool with { location: "Paris" }
// 3. Receive result
// 4. Generate natural language response

console.log(response.output_text);
// "The current weather in Paris is 72°F and sunny."

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: [tool1, tool2],
});

// Add a tool
agent.addTool(newTool);

// Remove a tool
agent.removeTool('tool_name');

// Replace all tools
agent.setTools([tool1, tool2, tool3]);

// List available tools
const toolNames = agent.listTools();
console.log(toolNames); // ['get_weather', 'calculate', 'search']

const myTool: ToolFunction = {
  definition: {
    type: 'function',
    function: {
      name: 'my_tool',
      description: 'Example tool',
      parameters: {
        type: 'object',
        properties: {
          input: { type: 'string' },
        },
        required: ['input'],
      },
    },
  },
  execute: async (args, context) => {
    // Identity (auto-populated from agent config):
    console.log(context?.agentId);  // Agent identifier
    console.log(context?.userId);   // User ID (set via agent.userId or config)

    // Connector registry (scoped to agent's userId + identities):
    if (context?.connectorRegistry) {
      const names = context.connectorRegistry.list();  // Available connector names
      const gh = context.connectorRegistry.get('github'); // Get connector instance
    }

    // Working memory (when workingMemory feature is enabled):
    if (context?.memory) {
      const data = await context.memory.get('some_key');
    }

    // Cancellation:
    if (context?.signal?.aborted) {
      return { error: 'Cancelled' };
    }

    return { result: 'done' };
  },
};

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  context: {
    model: 'gpt-4.1',
    features: {
      workingMemory: true,       // enables store="notes"
      inContextMemory: true,     // enables store="whiteboard"
      persistentInstructions: true, // enables store="instructions"
      userInfo: true,            // enables store="user_info"
      sharedWorkspace: true,     // enables store="workspace"
    },
  },
});

// The LLM uses these 5 tools to interact with all stores:
// - store_get(store, key?)       — get one entry or all
// - store_set(store, key, data)  — create/update entry
// - store_delete(store, key)     — remove entry
// - store_list(store, filter?)   — list entries
// - store_action(store, action, params?) — store-specific operations (query, clear, etc.)

// Examples:
// store_set("notes", "user.profile", { description: "User profile", value: { name: "Alice" }, priority: "high" })
// store_get("notes", "user.profile")
// store_set("whiteboard", "state", { description: "Current state", value: { step: 1 } })
// store_set("instructions", "tone", { content: "Be concise" })
// store_action("notes", "query", { tier: "findings" })

// Programmatic access (unchanged):
const memory = agent.context.memory;
await memory.store('user.profile', 'User profile', { name: 'Alice' }, 'high');
const profile = await memory.retrieve('user.profile');

const { input, budget } = await agent.context.prepare();

console.log(budget);
// {
//   maxTokens: 128000,
//   totalUsed: 45000,
//   available: 63800,
//   utilizationPercent: 35.2,
//   breakdown: {
//     systemPrompt: 500,
//     pluginInstructions: 800,
//     conversation: 38000,
//     currentInput: 200,
//   }
// }

import { createExecuteJavaScriptTool } from 'oneringai';

const jsTool = createExecuteJavaScriptTool();

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: [jsTool],
});

const response = await agent.run('Calculate the sum of numbers from 1 to 100');

// Agent will:
// 1. Generate JavaScript code
// 2. Execute: execute_javascript({ code: 'Array(100).fill(0).map((_, i) => i+1).reduce((a,b) => a+b)' })
// 3. Return result: 5050

import { Agent, Connector, Vendor, createCustomToolMetaTools } from 'oneringai';

Connector.create({
  name: 'openai',
  vendor: Vendor.OpenAI,
  auth: { type: 'api_key', apiKey: process.env.OPENAI_API_KEY! },
});

// Give the agent the ability to create tools
const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: [...createCustomToolMetaTools()],
});

// Ask the agent to create a tool
const response = await agent.run(
  'Create a tool called "celsius_to_fahrenheit" that converts temperature from Celsius to Fahrenheit'
);

// The agent will autonomously:
// 1. Call custom_tool_draft to validate the definition
// 2. Call custom_tool_test with sample inputs to verify
// 3. Call custom_tool_save to persist it

Agent calls: custom_tool_draft({
  name: "celsius_to_fahrenheit",
  description: "Converts temperature from Celsius to Fahrenheit",
  inputSchema: {
    type: "object",
    properties: { celsius: { type: "number" } },
    required: ["celsius"]
  },
  code: "output = { fahrenheit: input.celsius * 9/5 + 32 };"
})
→ Returns: { success: true, validated: { ... } }

Agent calls: custom_tool_test({
  code: "output = { fahrenheit: input.celsius * 9/5 + 32 };",
  inputSchema: { type: "object", properties: { celsius: { type: "number" } } },
  testInput: { celsius: 100 }
})
→ Returns: { success: true, result: { fahrenheit: 212 }, logs: [], executionTime: 3 }

Agent calls: custom_tool_save({
  name: "celsius_to_fahrenheit",
  description: "Converts temperature from Celsius to Fahrenheit",
  inputSchema: { ... },
  code: "output = { fahrenheit: input.celsius * 9/5 + 32 };",
  tags: ["conversion", "temperature"],
  category: "math"
})
→ Returns: { success: true, name: "celsius_to_fahrenheit", storagePath: "~/.oneringai/users/default/custom-tools/" }

SANDBOX API (available inside custom tool code):

1. authenticatedFetch(url, options, connectorName)
   Makes authenticated HTTP requests using the connector's credentials.
   Auth headers are added automatically — DO NOT set Authorization header manually.
   ...

REGISTERED CONNECTORS:
   • "github" (GitHub)
     Service: github
     URL: https://api.github.com

   • "slack" (Slack Workspace)
     Service: slack
     URL: https://slack.com/api

// Agent creates a tool that fetches GitHub repos
// (assuming a 'github' connector is registered)
await agent.run(
  'Create a tool called "list_repos" that lists all repositories for a given GitHub user. ' +
  'Use the github connector.'
);

// The agent will write code like:
// const resp = await authenticatedFetch(`/users/${input.username}/repos`, { method: 'GET' }, 'github');
// const repos = await resp.json();
// output = repos.map(r => ({ name: r.full_name, stars: r.stargazers_count }));

import {
  createFileCustomToolStorage,
  hydrateCustomTool,
  Agent,
} from 'oneringai';

// Load a saved tool (undefined = default user)
const storage = createFileCustomToolStorage();
const definition = await storage.load(undefined, 'celsius_to_fahrenheit');

if (definition) {
  // Hydrate into a live ToolFunction
  const tool = hydrateCustomTool(definition);

  // Register on any agent
  const agent = Agent.create({ connector: 'openai', model: 'gpt-4.1', tools: [tool] });

  // The agent can now use celsius_to_fahrenheit like any built-in tool
  const response = await agent.run('Convert 37°C to Fahrenheit');
}

const storage = createFileCustomToolStorage();
const userId = undefined; // or a specific userId for multi-tenant apps

// List all saved tools
const all = await storage.list(userId);

// Search by name or description
const mathTools = await storage.list(userId, { search: 'convert' });

// Filter by tags
const apiTools = await storage.list(userId, { tags: ['api'] });

// Filter by category
const networkTools = await storage.list(userId, { category: 'network' });

// Pagination
const page2 = await storage.list(userId, { limit: 10, offset: 10 });

import type { ICustomToolStorage, CustomToolListOptions } from 'oneringai';
import type { CustomToolDefinition, CustomToolSummary } from 'oneringai';

class MongoCustomToolStorage implements ICustomToolStorage {
  constructor(private db: Db) {}

  async save(userId: string | undefined, definition: CustomToolDefinition): Promise<void> {
    const user = userId || 'default';
    await this.db.collection('custom_tools').replaceOne(
      { userId: user, name: definition.name },
      { userId: user, ...definition },
      { upsert: true }
    );
  }

  async load(userId: string | undefined, name: string): Promise<CustomToolDefinition | null> {
    const user = userId || 'default';
    return this.db.collection('custom_tools').findOne({ userId: user, name });
  }

  async delete(userId: string | undefined, name: string): Promise<void> {
    const user = userId || 'default';
    await this.db.collection('custom_tools').deleteOne({ userId: user, name });
  }

  async exists(userId: string | undefined, name: string): Promise<boolean> {
    const user = userId || 'default';
    return (await this.db.collection('custom_tools').countDocuments({ userId: user, name })) > 0;
  }

  async list(userId: string | undefined, options?: CustomToolListOptions): Promise<CustomToolSummary[]> {
    const user = userId || 'default';
    const filter: any = { userId: user };
    if (options?.tags?.length) filter['metadata.tags'] = { $in: options.tags };
    if (options?.category) filter['metadata.category'] = options.category;
    if (options?.search) {
      filter.$or = [
        { name: { $regex: options.search, $options: 'i' } },
        { description: { $regex: options.search, $options: 'i' } },
      ];
    }

    return this.db.collection('custom_tools')
      .find(filter, { projection: { code: 0 } })  // Exclude code for summaries
      .sort({ updatedAt: -1 })
      .skip(options?.offset ?? 0)
      .limit(options?.limit ?? 100)
      .toArray();
  }

  getPath(userId: string | undefined): string { return `mongodb://custom_tools/${userId || 'default'}`; }
}

// Use with meta-tools
import { createCustomToolMetaTools } from 'oneringai';
const storage = new MongoCustomToolStorage(db);
const tools = createCustomToolMetaTools({ storage });

interface CustomToolDefinition {
  version: number;                         // Format version (currently 1)
  name: string;                            // Unique name (/^[a-z][a-z0-9_]*$/)
  displayName?: string;                    // Human-readable name
  description: string;                     // What the tool does
  inputSchema: Record<string, unknown>;    // JSON Schema (must have type: 'object')
  outputSchema?: Record<string, unknown>;  // Optional output schema (documentation only)
  code: string;                            // JavaScript code for the VM sandbox
  createdAt: string;                       // ISO timestamp
  updatedAt: string;                       // ISO timestamp
  metadata?: {
    tags?: string[];                       // Categorization tags
    category?: string;                     // Category grouping
    author?: string;                       // Creator identifier
    generationPrompt?: string;             // The prompt used to create this tool
    testCases?: CustomToolTestCase[];      // Saved test cases
    requiresConnector?: boolean;           // Whether connectors are needed
    connectorNames?: string[];             // Which connectors the tool uses
  };
}

const tool = hydrateCustomTool(definition);

agent.tools.register(tool, {
  source: 'custom',            // Track origin (built-in, connector, custom, mcp)
  tags: ['api', 'weather'],    // Categorization
  category: 'external-apis',   // Grouping
});

~/.oneringai/users/<userId>/custom-tools/
├── _index.json              # Index for fast listing and search
├── celsius_to_fahrenheit.json
├── fetch_weather.json
└── list_repos.json

import { developerTools } from 'oneringai';

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: developerTools, // All 11 tools included (filesystem, bash, dev server, background process management)
});

// Agent can now read, write, edit files, search, and run commands
await agent.run('Read the package.json and tell me the version');

import {
  createReadFileTool,
  createWriteFileTool,
  createEditFileTool,
  createGlobTool,
  createGrepTool,
  createListDirectoryTool,
  createBashTool,
} from 'oneringai';

// Create tools with custom configuration
const readFile = createReadFileTool({
  workingDirectory: '/path/to/project',
  maxFileSize: 5 * 1024 * 1024, // 5MB
});

const bash = createBashTool({
  workingDirectory: '/path/to/project',
  defaultTimeout: 60000, // 1 minute
  allowBackground: true,
});

// Text files — returns content with line numbers
read_file({
  file_path: '/path/to/file.ts',
  offset: 50,    // Start at line 50 (optional)
  limit: 100,    // Read 100 lines (optional)
});
// Returns: { success: true, content: "1\tconst x = 1;...", lines: 100 }

// Binary documents — auto-converted to markdown
read_file({ file_path: '/path/to/report.pdf' });
// Returns: { success: true, content: "# Document: report.pdf\n...", encoding: 'document' }

write_file({
  file_path: '/path/to/new/file.ts',
  content: 'export const hello = "world";',
});
// Returns: { success: true, created: true, bytesWritten: 29 }

edit_file({
  file_path: '/path/to/file.ts',
  old_string: 'const x = 1;',
  new_string: 'const x = 42;',
  replace_all: false, // Fails if old_string is not unique (default)
});
// Returns: { success: true, replacements: 1 }

glob({
  pattern: '**/*.ts',
  path: '/path/to/project', // Optional, defaults to cwd
});
// Returns: { success: true, files: ['src/index.ts', 'src/utils.ts', ...], count: 15 }

grep({
  pattern: 'function\\s+\\w+',
  path: '/path/to/project',
  type: 'ts',                      // Filter by file type
  output_mode: 'content',          // 'content', 'files_with_matches', 'count'
  case_insensitive: true,
  context_before: 2,               // Lines before match
  context_after: 2,                // Lines after match
});
// Returns: { success: true, matches: [...], filesMatched: 5, totalMatches: 23 }

list_directory({
  path: '/path/to/project',
  recursive: true,
  filter: 'files',     // 'files' or 'directories'
  max_depth: 3,
});
// Returns: { success: true, entries: [...], count: 42 }

bash({
  command: 'npm install',
  timeout: 300000,        // 5 minutes
  description: 'Install dependencies',
  run_in_background: false,
});
// Returns: { success: true, stdout: '...', exitCode: 0, duration: 5234 }

interface FilesystemToolConfig {
  workingDirectory?: string;       // Base directory (default: cwd)
  allowedDirectories?: string[];   // Restrict to these directories
  blockedDirectories?: string[];   // Block access (default: node_modules, .git)
  maxFileSize?: number;            // Max read size (default: 10MB)
  maxResults?: number;             // Max results for glob/grep (default: 1000)
  followSymlinks?: boolean;        // Follow symlinks (default: false)
  excludeExtensions?: string[];    // Skip binary files
}

interface ShellToolConfig {
  workingDirectory?: string;       // Working directory
  defaultTimeout?: number;         // Default timeout (default: 120000ms)
  maxTimeout?: number;             // Max timeout (default: 600000ms)
  maxOutputSize?: number;          // Max output size (default: 10MB)
  allowBackground?: boolean;       // Allow background execution (default: true)
  shell?: string;                  // Shell to use (default: /bin/bash)
  env?: Record<string, string>;    // Environment variables
}

import { desktopTools, Agent, Connector, Vendor } from 'oneringai';

// Setup
Connector.create({
  name: 'openai',
  vendor: Vendor.OpenAI,
  auth: { type: 'api_key', apiKey: process.env.OPENAI_API_KEY! },
});

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: desktopTools,
});

// The agent loop: screenshot → vision model → tool calls → repeat
await agent.run('Take a screenshot, then open the Calculator app and compute 42 * 17');

npm install @nut-tree-fork/nut-js

Screenshot pixels (2560×1600 on Retina) ← Tools accept these coords
         ↕ driver divides by scaleFactor
OS logical coords (1280×800)             ← nut-tree operates here

import { createDesktopScreenshotTool, createDesktopMouseClickTool } from 'oneringai';

// Custom config for individual tools
const screenshot = createDesktopScreenshotTool({
  humanDelay: [0, 0],        // No delay (instant actions)
  humanizeMovement: false,    // Straight-line mouse movement
});

// Or provide a custom driver implementation
import type { IDesktopDriver } from 'oneringai';

declare const myDriver: IDesktopDriver; // Supply a complete host implementation of the interface.
const click = createDesktopMouseClickTool({ driver: myDriver });

import { Agent, developerTools } from 'oneringai';

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: developerTools,
});

// read_file auto-detects binary formats and converts to markdown
await agent.run('Read /path/to/quarterly-report.pdf and summarize it');
await agent.run('Read /path/to/sales-data.xlsx and identify the top performers');
await agent.run('Read /path/to/onboarding.pptx and list the key steps');
await agent.run('Read /path/to/contract.docx and highlight important clauses');

import { Agent, tools } from 'oneringai';

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: [tools.webFetch],
});

// web_fetch detects PDF content-type and converts to markdown
await agent.run('Fetch https://example.com/annual-report.pdf and summarize it');

import { DocumentReader, mergeTextPieces } from 'oneringai';

// Create reader with defaults
const reader = DocumentReader.create({
  defaults: {
    maxTokens: 50_000,
    extractImages: true,
    imageFilter: { minWidth: 100, minHeight: 100 },
  },
});

// Read from different sources
const result = await reader.read('/path/to/report.pdf');
const resultVariant2 = await reader.read('https://example.com/doc.xlsx');
const resultVariant3 = await reader.read({ type: 'buffer', buffer: uploadedBuffer, filename: 'doc.docx' });
const resultVariant4 = await reader.read({ type: 'blob', blob: fileBlob, filename: 'slides.pptx' });

// Get merged text
const markdown = mergeTextPieces(resultVariant4.pieces);
console.log(markdown);

// Access individual pieces
for (const piece of resultVariant4.pieces) {
  if (piece.type === 'text') {
    console.log(`[${piece.metadata.section}] ${piece.content.substring(0, 100)}...`);
  } else {
    console.log(`[Image] ${piece.mimeType} (${piece.metadata.sizeBytes} bytes)`);
  }
}

// Metadata
console.log(resultVariant4.metadata.format);           // 'pdf'
console.log(resultVariant4.metadata.family);           // 'pdf'
console.log(resultVariant4.metadata.estimatedTokens);  // 12500
console.log(resultVariant4.metadata.totalPieces);      // 15
console.log(resultVariant4.metadata.totalImagePieces); // 3
console.log(resultVariant4.metadata.processingTimeMs); // 234

import { readDocumentAsContent, documentToContent } from 'oneringai';

// One-call convenience: read + filter + convert to Content[]
const content = await readDocumentAsContent('/path/to/slides.pptx', {
  extractImages: true,
  imageDetail: 'auto',
  imageFilter: { minWidth: 100, minHeight: 100 },
  maxImages: 20,
  mergeAdjacentText: true,
});

// Use with agent
const response = await agent.run([
  { type: 'input_text', text: 'Analyze this presentation:' },
  ...content,
]);

// Or use documentToContent() for two-step conversion
const reader = DocumentReader.create();
const result = await reader.read('/path/to/doc.pdf');
const contentVariant2 = documentToContent(result, {
  imageDetail: 'low',
  maxImages: 10,
});

const reader = DocumentReader.create({
  defaults: {
    maxTokens: 100_000,         // Max estimated tokens in output
    maxOutputBytes: 5_242_880,  // Max output size (5MB)
    extractImages: true,        // Extract images from documents
    imageDetail: 'auto',        // Image detail for LLM ('auto', 'low', 'high')
    imageFilter: {
      minWidth: 50,             // Skip images narrower than this
      minHeight: 50,            // Skip images shorter than this
      minSizeBytes: 1024,       // Skip images smaller than this
      maxImages: 50,            // Max images to keep
      excludePatterns: [/logo/i, /icon/i],  // Exclude by label pattern
    },
    formatOptions: {
      excel: {
        maxRows: 1000,          // Max rows per sheet
        maxColumns: 50,         // Max columns per sheet
        tableFormat: 'markdown', // 'markdown', 'csv', or 'json'
        includeFormulas: false,
      },
      pdf: {
        includeMetadata: true,  // Include title, author, page count
      },
      html: {
        maxLength: 50_000,      // Max HTML length to process
      },
      office: {
        includeSpeakerNotes: true, // Include PPTX speaker notes
      },
    },
  },
  maxDownloadSizeBytes: 50_000_000, // Max file size for URL sources (50MB)
  downloadTimeoutMs: 60_000,        // Download timeout for URL sources
});

// Per-call override
const result = await reader.read('/path/to/large.pdf', {
  maxTokens: 200_000,       // Override just for this call
  extractImages: false,      // Text-only for this call
  pages: [1, 2, 3],         // Only read specific pages
});

import type { IDocumentTransformer } from 'oneringai';

const myTransformer: IDocumentTransformer = {
  name: 'addWatermark',
  appliesTo: [],  // empty = all formats
  priority: 20,
  async transform(pieces, context) {
    // Add a watermark to each text piece
    return pieces.map(p => p.type === 'text'
      ? { ...p, content: p.content + '\n\n_Processed by MyApp_' }
      : p
    );
  },
};

const result = await reader.read('/path/to/doc.pdf', {
  transformers: [myTransformer],
});

import type { IFormatHandler } from 'oneringai';

const customPDFHandler: IFormatHandler = {
  name: 'MyPDFHandler',
  supportedFormats: ['pdf'],
  async handle(buffer, filename, format, options) {
    // Custom PDF parsing logic
    const text = await parsePdfText(buffer, options); // Your parser implementation.
    return [{ type: 'text', content: text, metadata: {
      sourceFilename: filename, format, index: 0, sizeBytes: buffer.length,
      estimatedTokens: Math.ceil(text.length / 4),
    } }];
  },
};

const reader = DocumentReader.create();
reader.registerHandler('pdf', customPDFHandler);

// Extraction-time filtering (in DocumentReader)
const result = await reader.read('/path/to/slides.pptx', {
  imageFilter: {
    minWidth: 100,       // Skip images narrower than 100px
    minHeight: 100,      // Skip images shorter than 100px
    minSizeBytes: 2048,  // Skip images smaller than 2KB
    maxImages: 30,       // Keep at most 30 images
    excludePatterns: [/logo/i, /background/i],
  },
});

// Content-conversion-time filtering (additional pass)
const content = documentToContent(result, {
  imageFilter: { minWidth: 200 },  // Stricter for LLM input
  maxImages: 10,                    // Fewer images for LLM
  imageDetail: 'low',               // Low detail saves tokens
});

import { AIError } from 'oneringai';

try {
  const result = await reader.read('/path/to/file.xyz');
} catch (error) {
  if (error instanceof AIError && error.code === 'UNSUPPORTED_FORMAT') {
    console.log(`Format not supported: ${error.message}`);
  } else if (error instanceof AIError && error.code === 'DOCUMENT_READ_ERROR') {
    console.log(`Read failed: ${error.message}`);
  }
}

import { Agent, tools } from 'oneringai';

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: [tools.webFetch],
});

await agent.run('Fetch https://example.com and summarize it');

import { Connector, ConnectorTools, Agent, tools } from 'oneringai';

// Create a search connector
Connector.create({
  name: 'serper',
  serviceType: 'serper',
  auth: { type: 'api_key', apiKey: process.env.SERPER_API_KEY! },
  baseURL: 'https://google.serper.dev',
});

// Get search tools from the connector
const searchTools = ConnectorTools.for('serper');

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: [tools.webFetch, ...searchTools],
});

await agent.run('Search for the latest Node.js release');

import { Connector, ConnectorTools } from 'oneringai';

Connector.create({
  name: 'zenrows',
  serviceType: 'zenrows',
  auth: { type: 'api_key', apiKey: process.env.ZENROWS_API_KEY! },
  baseURL: 'https://api.zenrows.com/v1',
});

const scrapeTools = ConnectorTools.for('zenrows');

import { Agent, tools } from 'oneringai';

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: [tools.jsonManipulator],
});

await agent.run('Add a "version" field set to "2.0" to this JSON: {"name": "app"}');

import { Connector, ConnectorTools, Services, Agent } from 'oneringai';

// Create a GitHub connector
Connector.create({
  name: 'github',
  serviceType: Services.Github,
  auth: { type: 'api_key', apiKey: process.env.GITHUB_TOKEN! },
  baseURL: 'https://api.github.com',
  options: {
    defaultRepository: 'myorg/myrepo', // Optional: default repo for all tools
  },
});

// Get all GitHub tools (generic API + 8 dedicated tools)
const tools = ConnectorTools.for('github');

// Use with an agent
const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: tools,
});

// Agent can now search files, read code, analyze PRs, and create PRs
await agent.run('Find all TypeScript files in src/ and show me the main entry point');
await agent.run('Show me PR #42 and summarize the changes');

// Find TypeScript files
{ "pattern": "**/*.ts" }

// Search in specific path
{ "pattern": "src/components/**/*.tsx", "repository": "facebook/react" }

// Search specific branch
{ "pattern": "**/*.test.ts", "ref": "develop" }

// Find function usage
{ "query": "handleAuth", "language": "typescript" }

// Search in specific path
{ "query": "TODO", "path": "src/utils", "extension": "ts" }

// Read entire file
{ "path": "src/index.ts" }

// Read specific lines
{ "path": "src/app.ts", "offset": 100, "limit": 50 }

// Read from specific branch
{ "path": "README.md", "ref": "develop" }

{ "pull_number": 42 }
{ "pull_number": 42, "repository": "owner/repo" }

{ "pull_number": 42 }

{ "pull_number": 42 }

// Basic PR
{ "title": "Add feature", "head": "feature-branch", "base": "main" }

// Draft PR with description
{
  "title": "WIP: Refactor auth",
  "body": "## Changes\n- Refactored auth flow\n- Added tests",
  "head": "refactor/auth",
  "base": "main",
  "draft": true
}

import {
  createSearchFilesTool,
  createSearchCodeTool,
  createGitHubReadFileTool,
  createListBranchesTool,
  createGetPRTool,
  createPRFilesTool,
  createPRCommentsTool,
  createCreatePRTool,
  parseRepository,
} from 'oneringai';

// Create individual tools from a connector
const connector = Connector.get('github');
const searchFiles = createSearchFilesTool(connector);
const readFile = createGitHubReadFileTool(connector);

// Use parseRepository for URL resolution
const { owner, repo } = parseRepository('https://github.com/facebook/react');

import {
  Agent,
  ConnectorTools,
  createConnectorFromTemplate,
} from 'oneringai';

createConnectorFromTemplate(
  'work-slack',
  'slack',
  'bot-token',
  { apiKey: process.env.SLACK_BOT_TOKEN! },
);

const slackTools = ConnectorTools.for('work-slack');

const agent = Agent.create({
  connector: 'openai-main',
  model: 'gpt-5.6-terra',
  identities: [{ connector: 'work-slack' }],
  tools: slackTools,
});

import { Connector, ConnectorTools, Services, Agent } from 'oneringai';

// Create a Microsoft connector with OAuth
Connector.create({
  name: 'microsoft',
  serviceType: Services.Microsoft,
  auth: {
    type: 'oauth', flow: 'authorization_code',
    clientId: process.env.MICROSOFT_CLIENT_ID!,
    clientSecret: process.env.MICROSOFT_CLIENT_SECRET!,
    redirectUri: 'http://localhost:3000/callback',
    authorizationUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
    tokenUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
    scope: 'https://graph.microsoft.com/.default offline_access',
  },
  baseURL: 'https://graph.microsoft.com/v1.0',
});

// Get all Microsoft tools (generic API + 11 dedicated tools)
const tools = ConnectorTools.for('microsoft');

// Use with an agent
const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: tools,
});

await agent.run('Draft an email to alice@example.com about the project update');
await agent.run('Schedule a 30-minute Teams meeting with bob@example.com next Tuesday at 2pm');
await agent.run('Find my recent files in OneDrive about the project plan');

// New draft
{ "to": ["alice@example.com"], "subject": "Project Update", "body": "<p>Here's the latest...</p>" }

// Reply draft
{ "to": ["alice@example.com"], "subject": "Re: Project", "body": "<p>Thanks!</p>", "replyToMessageId": "AAMkAG..." }

// Send new email
{ "to": ["bob@example.com"], "subject": "Meeting Notes", "body": "<p>Attached are the notes.</p>" }

// Reply to existing message
{ "to": ["bob@example.com"], "subject": "Re: Meeting Notes", "body": "<p>Thanks!</p>", "replyToMessageId": "AAMkAG..." }

// Simple meeting
{
  "subject": "Sprint Review",
  "startDateTime": "2026-03-01T14:00:00",
  "endDateTime": "2026-03-01T14:30:00",
  "attendees": ["alice@example.com", "bob@example.com"],
  "isOnlineMeeting": true,
  "timeZone": "America/New_York"
}

{ "eventId": "AAMkAG...", "subject": "Updated Sprint Review", "attendees": ["alice@example.com", "bob@example.com", "charlie@example.com"] }

{
  "attendees": ["alice@example.com", "bob@example.com"],
  "startDateTime": "2026-03-01T08:00:00",
  "endDateTime": "2026-03-05T18:00:00",
  "duration": 30,
  "timeZone": "America/New_York",
  "maxResults": 5
}

// By meeting ID
{ "meetingId": "MSoxMjM0NTY3..." }

// By Teams join URL
{ "meetingId": "https://teams.microsoft.com/l/meetup-join/..." }

import { createConnectorFromTemplate, Agent, Vendor, Connector } from 'oneringai';

// Create Telegram connector
createConnectorFromTemplate('my-bot', 'telegram', 'bot-token', {
  apiKey: process.env.TELEGRAM_BOT_TOKEN!,
});

// Agent with Telegram tools
const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  identities: [{ connector: 'my-bot' }],  // Enables Telegram tools
});

import { createConnectorFromTemplate } from 'oneringai';

createConnectorFromTemplate('my-twilio', 'twilio', 'api-key', {
  apiKey: process.env.TWILIO_AUTH_TOKEN!,
  accountId: process.env.TWILIO_ACCOUNT_SID!,
}, {
  vendorOptions: {
    defaultFromNumber: '+15551234567',
    defaultWhatsAppNumber: '+15551234567',
  },
});

import { Connector, ConnectorTools, Agent, Vendor } from 'oneringai';

// Create Google OAuth connector
Connector.create({
  name: 'google',
  vendor: Vendor.Google,
  baseURL: 'https://www.googleapis.com',
  auth: {
    type: 'oauth', flow: 'authorization_code',
    clientId: process.env.GOOGLE_CLIENT_ID!,
    clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    redirectUri: 'http://localhost:3000/callback',
    authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
    tokenUrl: 'https://oauth2.googleapis.com/token',
    scope: 'https://www.googleapis.com/auth/gmail.compose https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/drive.readonly',
  },
  serviceType: 'google-api',
});

// Get all Google tools (generic API + 11 dedicated tools)
const tools = ConnectorTools.for('google');

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools,
});

await agent.run('Draft an email to alice@example.com about the project update');
await agent.run('Create a calendar event for next Tuesday at 2pm with Google Meet');
await agent.run('Search my Drive for the Q4 report');

import { createConnectorFromTemplate, ConnectorTools } from 'oneringai';

// OAuth User Token
createConnectorFromTemplate('my-zoom', 'zoom', 'oauth-user', {
  clientId: process.env.ZOOM_CLIENT_ID!,
  redirectUri: 'http://localhost:3000/callback',
});

// Or Server-to-Server OAuth
createConnectorFromTemplate('zoom-s2s', 'zoom', 'server-to-server', {
  clientId: process.env.ZOOM_S2S_CLIENT_ID!,
  clientSecret: process.env.ZOOM_S2S_CLIENT_SECRET!,
  accountId: process.env.ZOOM_ACCOUNT_ID!,
});

import { tools } from 'oneringai';

// Create providers from existing connectors
const googleProvider = tools.createGoogleCalendarSlotsProvider(googleConnector);
const msftProvider = tools.createMicrosoftCalendarSlotsProvider(msftConnector);

// Unified tool checks all providers in parallel
const tool = tools.createUnifiedFindMeetingSlotsTool([googleProvider, msftProvider]);

const result = await tool.execute({
  attendees: ['alice@gmail.com', 'bob@outlook.com'],
  startDateTime: '2026-04-15T08:00:00',
  endDateTime: '2026-04-15T18:00:00',
  duration: 30,
  timeZone: 'America/New_York',
  maxResults: 5,
  // Optional: route attendees to specific providers
  attendeeMapping: {
    'alice@gmail.com': 'Google',
    'bob@outlook.com': 'Microsoft',
  },
});
// result.slots: MeetingSlotSuggestion[] — times when ALL attendees are free

interface ICalendarSlotsProvider {
  readonly name: string;
  execute(args: GetBusyIntervalsArgs): Promise<GetBusyIntervalsResult>;
}

import { Agent, Connector, Vendor } from 'oneringai';

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  identities: [
    { connector: 'microsoft', accountId: 'work' },
    { connector: 'microsoft', accountId: 'personal' },
    { connector: 'google', accountId: 'main', toolFilter: ['send_email', 'read_file'] },
  ],
});

// Re-key a temporary account ID to a stable one (e.g., after discovering email)
await connector.rekeyAccount('user-123', 'temp-abc', 'alice@work.com');

// Remove an account
await connector.removeAccount('user-123', 'personal');

// List all accounts for a user
const accounts = await connector.listAccounts('user-123');