thaddeus 1.0.18 → 1.0.27

package/src/tools/ContactsTool/ContactsTool.js

@@ -0,0 +1,648 @@
+/**
+ * ContactsTool.ts — CRM contacts manager for Thaddeus.
+ *
+ * Ported from Oracle Business (oracle-agent/src/tools/contacts.js).
+ * Provides CRUD + search + tagging + bulk import for contacts backed by SQLite.
+ *
+ * Key differences from the Oracle Business version:
+ * - TypeScript with Zod validation (not raw JS)
+ * - Uses bun:sqlite prepared statements (no string interpolation SQL)
+ * - Follows Thaddeus buildTool() pattern exactly
+ * - Database stored at ~/.thaddeus/business.db (shared with all business tools)
+ */
+import { z } from 'zod/v4';
+import { buildTool } from '../../Tool.js';
+import { lazySchema } from '../../utils/lazySchema.js';
+import { queryAll, queryOne, queryValue, run, formatDateTime, nowStr, getBusinessDb, } from '../../utils/businessDb.js';
+import { CONTACTS_TOOL_NAME } from './constants.js';
+import { DESCRIPTION, PROMPT } from './prompt.js';
+// ---------------------------------------------------------------------------
+// Zod schemas
+// ---------------------------------------------------------------------------
+const ActionEnum = z.enum([
+    'add',
+    'search',
+    'get',
+    'update',
+    'list',
+    'delete',
+    'stats',
+    'import',
+    'tag',
+]);
+const inputSchema = lazySchema(() => z.strictObject({
+    action: ActionEnum.describe('Action to perform'),
+    id: z
+        .number()
+        .int()
+        .optional()
+        .describe('Contact id for get, update, delete, or tag'),
+    name: z.string().optional().describe('Contact full name (required for add)'),
+    email: z.string().optional().describe('Contact email address'),
+    phone: z.string().optional().describe('Contact phone number'),
+    business_name: z.string().optional().describe('Business or company name'),
+    industry: z.string().optional().describe('Industry sector'),
+    source: z
+        .string()
+        .optional()
+        .describe('Lead source (e.g. referral, website, cold-call)'),
+    address: z.string().optional().describe('Street address'),
+    city: z.string().optional().describe('City'),
+    state: z.string().optional().describe('State/province'),
+    zip: z.string().optional().describe('ZIP/postal code'),
+    status: z
+        .enum(['prospect', 'active', 'lead', 'customer', 'inactive'])
+        .optional()
+        .describe('Contact status'),
+    notes: z.string().optional().describe('Free-form notes'),
+    tags: z.string().optional().describe('Comma-separated tags'),
+    preferred_contact: z
+        .string()
+        .optional()
+        .describe('Preferred contact method (email, phone, sms)'),
+    timezone: z.string().optional().describe('Contact timezone'),
+    query: z
+        .string()
+        .optional()
+        .describe('Search query for the search action'),
+    tag: z
+        .string()
+        .optional()
+        .describe('Tag name for the tag action'),
+    tag_action: z
+        .enum(['add', 'remove'])
+        .optional()
+        .describe('Whether to add or remove the tag'),
+    csv_data: z
+        .string()
+        .optional()
+        .describe('CSV string for bulk import (first row = headers)'),
+    limit: z
+        .number()
+        .int()
+        .optional()
+        .describe('Max results to return (default 25)'),
+    offset: z
+        .number()
+        .int()
+        .optional()
+        .describe('Pagination offset (default 0)'),
+}));
+const outputSchema = lazySchema(() => z.object({
+    success: z.boolean(),
+    output: z.string(),
+}));
+// ---------------------------------------------------------------------------
+// Column safelist for updates
+// ---------------------------------------------------------------------------
+const UPDATABLE_COLUMNS = new Set([
+    'name',
+    'email',
+    'phone',
+    'business_name',
+    'industry',
+    'source',
+    'address',
+    'city',
+    'state',
+    'zip',
+    'status',
+    'notes',
+    'tags',
+    'preferred_contact',
+    'timezone',
+]);
+// ---------------------------------------------------------------------------
+// Validation helpers
+// ---------------------------------------------------------------------------
+function isValidEmail(email) {
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}
+function isValidPhone(phone) {
+    // Allow digits, spaces, dashes, parens, plus — at least 7 digits
+    const digits = phone.replace(/\D/g, '');
+    return digits.length >= 7 && digits.length <= 15;
+}
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+function formatContact(row, interactionCount) {
+    const lines = [`#${row.id} ${row.name}`];
+    if (row.email)
+        lines.push(`Email: ${row.email}`);
+    if (row.phone)
+        lines.push(`Phone: ${row.phone}`);
+    if (row.business_name)
+        lines.push(`Business: ${row.business_name}`);
+    if (row.industry)
+        lines.push(`Industry: ${row.industry}`);
+    if (row.source)
+        lines.push(`Source: ${row.source}`);
+    lines.push(`Status: ${row.status}`);
+    if (row.address || row.city || row.state || row.zip) {
+        const addrParts = [row.address, row.city, row.state, row.zip].filter(Boolean);
+        lines.push(`Address: ${addrParts.join(', ')}`);
+    }
+    if (row.tags)
+        lines.push(`Tags: ${row.tags}`);
+    if (row.preferred_contact)
+        lines.push(`Preferred: ${row.preferred_contact}`);
+    if (row.timezone)
+        lines.push(`Timezone: ${row.timezone}`);
+    if (row.notes)
+        lines.push(`Notes: ${row.notes}`);
+    if (interactionCount !== undefined) {
+        lines.push(`Interactions: ${interactionCount}`);
+    }
+    lines.push(`Created: ${formatDateTime(row.created_at)}`);
+    if (row.updated_at !== row.created_at) {
+        lines.push(`Updated: ${formatDateTime(row.updated_at)}`);
+    }
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// CSV parser (handles quoted fields with commas)
+// ---------------------------------------------------------------------------
+function parseCSVLine(line) {
+    const fields = [];
+    let current = '';
+    let inQuotes = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (inQuotes) {
+            if (ch === '"') {
+                // Check for escaped quote
+                if (i + 1 < line.length && line[i + 1] === '"') {
+                    current += '"';
+                    i++;
+                }
+                else {
+                    inQuotes = false;
+                }
+            }
+            else {
+                current += ch;
+            }
+        }
+        else {
+            if (ch === '"') {
+                inQuotes = true;
+            }
+            else if (ch === ',') {
+                fields.push(current.trim());
+                current = '';
+            }
+            else {
+                current += ch;
+            }
+        }
+    }
+    fields.push(current.trim());
+    return fields;
+}
+// ---------------------------------------------------------------------------
+// Action handlers
+// ---------------------------------------------------------------------------
+function handleAdd(input) {
+    if (!input.name?.trim()) {
+        return { success: false, output: 'Error: name is required.' };
+    }
+    if (input.email && !isValidEmail(input.email)) {
+        return {
+            success: false,
+            output: `Error: invalid email format "${input.email}".`,
+        };
+    }
+    if (input.phone && !isValidPhone(input.phone)) {
+        return {
+            success: false,
+            output: `Error: invalid phone format "${input.phone}". Must contain 7-15 digits.`,
+        };
+    }
+    const now = nowStr();
+    run(`INSERT INTO contacts (name, email, phone, business_name, industry, source, address, city, state, zip, status, notes, tags, preferred_contact, timezone, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, input.name.trim(), input.email ?? null, input.phone ?? null, input.business_name ?? '', input.industry ?? '', input.source ?? '', input.address ?? '', input.city ?? '', input.state ?? '', input.zip ?? '', input.status ?? 'prospect', input.notes ?? '', input.tags ?? '', input.preferred_contact ?? '', input.timezone ?? '', now, now);
+    const row = queryOne('SELECT * FROM contacts WHERE rowid = last_insert_rowid()');
+    if (!row) {
+        return { success: false, output: 'Error: contact created but could not be retrieved.' };
+    }
+    return {
+        success: true,
+        output: `Contact created:\n${formatContact(row)}`,
+    };
+}
+function handleSearch(input) {
+    if (!input.query?.trim()) {
+        return { success: false, output: 'Error: query is required for search.' };
+    }
+    const q = `%${input.query.trim()}%`;
+    const rows = queryAll(`SELECT * FROM contacts
+     WHERE (name LIKE ? OR email LIKE ? OR phone LIKE ? OR business_name LIKE ?)
+       AND status != 'inactive'
+     ORDER BY updated_at DESC
+     LIMIT 20`, q, q, q, q);
+    if (!rows.length) {
+        return { success: true, output: `No contacts found matching "${input.query}".` };
+    }
+    return {
+        success: true,
+        output: `Found ${rows.length} contact(s):\n\n${rows.map(r => formatContact(r)).join('\n\n')}`,
+    };
+}
+function handleGet(input) {
+    if (input.id === undefined) {
+        return { success: false, output: 'Error: id is required for get.' };
+    }
+    const row = queryOne('SELECT * FROM contacts WHERE id = ?', input.id);
+    if (!row) {
+        return { success: false, output: `Error: contact #${input.id} not found.` };
+    }
+    const interactionCount = queryValue('SELECT COUNT(*) FROM interactions WHERE contact_id = ?', input.id);
+    return {
+        success: true,
+        output: formatContact(row, interactionCount),
+    };
+}
+function handleUpdate(input) {
+    if (input.id === undefined) {
+        return { success: false, output: 'Error: id is required for update.' };
+    }
+    const existing = queryOne('SELECT * FROM contacts WHERE id = ?', input.id);
+    if (!existing) {
+        return { success: false, output: `Error: contact #${input.id} not found.` };
+    }
+    // Validate email/phone if being updated
+    if (input.email !== undefined && input.email && !isValidEmail(input.email)) {
+        return {
+            success: false,
+            output: `Error: invalid email format "${input.email}".`,
+        };
+    }
+    if (input.phone !== undefined && input.phone && !isValidPhone(input.phone)) {
+        return {
+            success: false,
+            output: `Error: invalid phone format "${input.phone}". Must contain 7-15 digits.`,
+        };
+    }
+    // Build dynamic update from provided fields
+    const setClauses = [];
+    const params = [];
+    for (const col of UPDATABLE_COLUMNS) {
+        const val = input[col];
+        if (val !== undefined) {
+            setClauses.push(`${col} = ?`);
+            params.push(val);
+        }
+    }
+    if (!setClauses.length) {
+        return { success: false, output: 'Error: no fields provided to update.' };
+    }
+    setClauses.push('updated_at = ?');
+    params.push(nowStr());
+    params.push(input.id);
+    run(`UPDATE contacts SET ${setClauses.join(', ')} WHERE id = ?`, ...params);
+    const updated = queryOne('SELECT * FROM contacts WHERE id = ?', input.id);
+    if (!updated) {
+        return { success: false, output: 'Error: contact not found after update.' };
+    }
+    return {
+        success: true,
+        output: `Contact updated:\n${formatContact(updated)}`,
+    };
+}
+function handleList(input) {
+    const limit = input.limit ?? 25;
+    const offset = input.offset ?? 0;
+    const whereClauses = [];
+    const params = [];
+    if (input.status) {
+        whereClauses.push('status = ?');
+        params.push(input.status);
+    }
+    if (input.industry) {
+        whereClauses.push('industry = ?');
+        params.push(input.industry);
+    }
+    if (input.source) {
+        whereClauses.push('source = ?');
+        params.push(input.source);
+    }
+    if (input.tag) {
+        // Tags are comma-separated — use LIKE for substring match
+        whereClauses.push("tags LIKE ?");
+        params.push(`%${input.tag}%`);
+    }
+    const where = whereClauses.length ? `WHERE ${whereClauses.join(' AND ')}` : '';
+    const totalCount = queryValue(`SELECT COUNT(*) FROM contacts ${where}`, ...params);
+    const rows = queryAll(`SELECT * FROM contacts ${where} ORDER BY updated_at DESC LIMIT ? OFFSET ?`, ...params, limit, offset);
+    if (!rows.length) {
+        return { success: true, output: 'No contacts found.' };
+    }
+    const header = `Showing ${rows.length} of ${totalCount} contacts (offset ${offset}):`;
+    return {
+        success: true,
+        output: `${header}\n\n${rows.map(r => formatContact(r)).join('\n\n')}`,
+    };
+}
+function handleDelete(input) {
+    if (input.id === undefined) {
+        return { success: false, output: 'Error: id is required for delete.' };
+    }
+    const existing = queryOne('SELECT * FROM contacts WHERE id = ?', input.id);
+    if (!existing) {
+        return { success: false, output: `Error: contact #${input.id} not found.` };
+    }
+    if (existing.status === 'inactive') {
+        return {
+            success: true,
+            output: `Contact #${input.id} "${existing.name}" is already inactive.`,
+        };
+    }
+    // Soft-delete: set status to inactive
+    run('UPDATE contacts SET status = ?, updated_at = ? WHERE id = ?', 'inactive', nowStr(), input.id);
+    return {
+        success: true,
+        output: `Contact #${input.id} "${existing.name}" set to inactive (soft-deleted).`,
+    };
+}
+function handleStats() {
+    const byStatus = queryAll("SELECT status, COUNT(*) as count FROM contacts GROUP BY status ORDER BY count DESC");
+    const byIndustry = queryAll("SELECT industry, COUNT(*) as count FROM contacts WHERE industry != '' GROUP BY industry ORDER BY count DESC LIMIT 10");
+    const bySource = queryAll("SELECT source, COUNT(*) as count FROM contacts WHERE source != '' GROUP BY source ORDER BY count DESC LIMIT 10");
+    const totalActive = queryValue("SELECT COUNT(*) FROM contacts WHERE status != 'inactive'");
+    const totalInactive = queryValue("SELECT COUNT(*) FROM contacts WHERE status = 'inactive'");
+    const lines = ['Contact Statistics'];
+    lines.push(`Total active: ${totalActive}`);
+    lines.push(`Total inactive: ${totalInactive}`);
+    if (byStatus.length) {
+        lines.push('');
+        lines.push('By Status:');
+        for (const row of byStatus) {
+            lines.push(`  ${row.status}: ${row.count}`);
+        }
+    }
+    if (byIndustry.length) {
+        lines.push('');
+        lines.push('By Industry (top 10):');
+        for (const row of byIndustry) {
+            lines.push(`  ${row.industry}: ${row.count}`);
+        }
+    }
+    if (bySource.length) {
+        lines.push('');
+        lines.push('By Source (top 10):');
+        for (const row of bySource) {
+            lines.push(`  ${row.source}: ${row.count}`);
+        }
+    }
+    return { success: true, output: lines.join('\n') };
+}
+function handleImport(input) {
+    if (!input.csv_data?.trim()) {
+        return { success: false, output: 'Error: csv_data is required for import.' };
+    }
+    const lines = input.csv_data.trim().split('\n');
+    if (lines.length < 2) {
+        return {
+            success: false,
+            output: 'Error: CSV must have at least a header row and one data row.',
+        };
+    }
+    const headers = parseCSVLine(lines[0]).map(h => h.toLowerCase().replace(/\s+/g, '_'));
+    const allowedHeaders = new Set([
+        'name', 'email', 'phone', 'business_name', 'industry', 'source',
+        'address', 'city', 'state', 'zip', 'status', 'notes', 'tags',
+        'preferred_contact', 'timezone',
+    ]);
+    // Filter to only allowed columns
+    const columnMap = [];
+    for (let i = 0; i < headers.length; i++) {
+        const h = headers[i];
+        if (allowedHeaders.has(h)) {
+            columnMap.push({ headerIndex: i, column: h });
+        }
+    }
+    if (!columnMap.some(c => c.column === 'name')) {
+        return {
+            success: false,
+            output: 'Error: CSV must have a "name" column.',
+        };
+    }
+    let successCount = 0;
+    let failCount = 0;
+    const errors = [];
+    const now = nowStr();
+    for (let lineNum = 1; lineNum < lines.length; lineNum++) {
+        const line = lines[lineNum].trim();
+        if (!line)
+            continue;
+        try {
+            const fields = parseCSVLine(line);
+            const record = {};
+            for (const { headerIndex, column } of columnMap) {
+                record[column] = fields[headerIndex] ?? '';
+            }
+            if (!record['name']?.trim()) {
+                failCount++;
+                errors.push(`Row ${lineNum + 1}: missing name`);
+                continue;
+            }
+            // Validate email if present
+            if (record['email'] && !isValidEmail(record['email'])) {
+                failCount++;
+                errors.push(`Row ${lineNum + 1}: invalid email "${record['email']}"`);
+                continue;
+            }
+            run(`INSERT INTO contacts (name, email, phone, business_name, industry, source, address, city, state, zip, status, notes, tags, preferred_contact, timezone, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, record['name'].trim(), record['email'] || null, record['phone'] || null, record['business_name'] ?? '', record['industry'] ?? '', record['source'] ?? '', record['address'] ?? '', record['city'] ?? '', record['state'] ?? '', record['zip'] ?? '', record['status'] || 'prospect', record['notes'] ?? '', record['tags'] ?? '', record['preferred_contact'] ?? '', record['timezone'] ?? '', now, now);
+            successCount++;
+        }
+        catch (err) {
+            failCount++;
+            const msg = err instanceof Error ? err.message : String(err);
+            errors.push(`Row ${lineNum + 1}: ${msg}`);
+        }
+    }
+    const resultLines = [`Import complete: ${successCount} succeeded, ${failCount} failed.`];
+    if (errors.length) {
+        resultLines.push('');
+        resultLines.push('Errors:');
+        for (const e of errors.slice(0, 20)) {
+            resultLines.push(`  - ${e}`);
+        }
+        if (errors.length > 20) {
+            resultLines.push(`  ... and ${errors.length - 20} more`);
+        }
+    }
+    return { success: true, output: resultLines.join('\n') };
+}
+function handleTag(input) {
+    if (input.id === undefined) {
+        return { success: false, output: 'Error: id is required for tag.' };
+    }
+    if (!input.tag?.trim()) {
+        return { success: false, output: 'Error: tag is required.' };
+    }
+    const tagAction = input.tag_action ?? 'add';
+    const existing = queryOne('SELECT * FROM contacts WHERE id = ?', input.id);
+    if (!existing) {
+        return { success: false, output: `Error: contact #${input.id} not found.` };
+    }
+    const currentTags = existing.tags
+        ? existing.tags
+            .split(',')
+            .map(t => t.trim())
+            .filter(Boolean)
+        : [];
+    const targetTag = input.tag.trim();
+    if (tagAction === 'add') {
+        if (currentTags.includes(targetTag)) {
+            return {
+                success: true,
+                output: `Contact #${input.id} already has tag "${targetTag}".`,
+            };
+        }
+        currentTags.push(targetTag);
+    }
+    else {
+        const idx = currentTags.indexOf(targetTag);
+        if (idx === -1) {
+            return {
+                success: true,
+                output: `Contact #${input.id} does not have tag "${targetTag}".`,
+            };
+        }
+        currentTags.splice(idx, 1);
+    }
+    const newTags = currentTags.join(',');
+    run('UPDATE contacts SET tags = ?, updated_at = ? WHERE id = ?', newTags, nowStr(), input.id);
+    const verb = tagAction === 'add' ? 'added to' : 'removed from';
+    return {
+        success: true,
+        output: `Tag "${targetTag}" ${verb} contact #${input.id} "${existing.name}". Tags: ${newTags || '(none)'}`,
+    };
+}
+// ---------------------------------------------------------------------------
+// Tool definition
+// ---------------------------------------------------------------------------
+export const ContactsTool = buildTool({
+    name: CONTACTS_TOOL_NAME,
+    searchHint: 'CRM contacts customers prospects leads database',
+    maxResultSizeChars: 200_000,
+    shouldDefer: true,
+    async description() {
+        return DESCRIPTION;
+    },
+    async prompt() {
+        return PROMPT;
+    },
+    get inputSchema() {
+        return inputSchema();
+    },
+    get outputSchema() {
+        return outputSchema();
+    },
+    userFacingName() {
+        return 'Contacts';
+    },
+    isEnabled() {
+        return true;
+    },
+    isConcurrencySafe() {
+        return false;
+    },
+    isReadOnly(input) {
+        const readOnlyActions = new Set(['search', 'get', 'list', 'stats']);
+        return readOnlyActions.has(input.action);
+    },
+    isDestructive(input) {
+        return input.action === 'delete';
+    },
+    toAutoClassifierInput(input) {
+        const parts = [input.action];
+        if (input.name)
+            parts.push(input.name);
+        if (input.query)
+            parts.push(input.query.slice(0, 100));
+        return parts.join(' ');
+    },
+    getActivityDescription(input) {
+        if (!input?.action)
+            return 'Managing contacts';
+        const actionLabels = {
+            add: 'Adding contact',
+            search: 'Searching contacts',
+            get: 'Getting contact details',
+            update: 'Updating contact',
+            list: 'Listing contacts',
+            delete: 'Deleting contact',
+            stats: 'Getting contact stats',
+            import: 'Importing contacts',
+            tag: 'Tagging contact',
+        };
+        const label = actionLabels[input.action] ?? 'Managing contacts';
+        if (input.name)
+            return `${label}: ${input.name}`;
+        return label;
+    },
+    async checkPermissions(input) {
+        const readOnlyActions = new Set(['search', 'get', 'list', 'stats']);
+        if (readOnlyActions.has(input.action)) {
+            return { behavior: 'allow', updatedInput: input };
+        }
+        return { behavior: 'allow', updatedInput: input };
+    },
+    renderToolUseMessage(input) {
+        return null;
+    },
+    async call(input, context) {
+        try {
+            // Ensure DB is initialized
+            getBusinessDb();
+            switch (input.action) {
+                case 'add':
+                    return { data: handleAdd(input) };
+                case 'search':
+                    return { data: handleSearch(input) };
+                case 'get':
+                    return { data: handleGet(input) };
+                case 'update':
+                    return { data: handleUpdate(input) };
+                case 'list':
+                    return { data: handleList(input) };
+                case 'delete':
+                    return { data: handleDelete(input) };
+                case 'stats':
+                    return { data: handleStats() };
+                case 'import':
+                    return { data: handleImport(input) };
+                case 'tag':
+                    return { data: handleTag(input) };
+                default:
+                    return {
+                        data: {
+                            success: false,
+                            output: `Unknown action: ${input.action}`,
+                        },
+                    };
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                data: {
+                    success: false,
+                    output: `Error executing ${input.action}: ${message}`,
+                },
+            };
+        }
+    },
+    mapToolResultToToolResultBlockParam(content, toolUseID) {
+        const output = content;
+        return {
+            tool_use_id: toolUseID,
+            type: 'tool_result',
+            content: output.output,
+        };
+    },
+});

package/src/tools/ContactsTool/constants.js

@@ -0,0 +1 @@
+export const CONTACTS_TOOL_NAME = 'Contacts';

package/src/tools/ContactsTool/prompt.js

@@ -0,0 +1,15 @@
+export const DESCRIPTION = `CRM contacts manager backed by SQLite.
+
+Actions:
+- add: Create a new contact (name required; email, phone, business_name, industry, source, notes, tags optional)
+- search: Fuzzy search across name, email, phone, business_name (top 20 results)
+- get: Get a single contact by id, including recent interaction count
+- update: Update specific fields on a contact by id (only provided fields change)
+- list: List contacts with optional filters (status, industry, source, tag) and pagination
+- delete: Soft-delete a contact (sets status to inactive; never hard-deletes)
+- stats: Contact statistics — counts by status, industry, source
+- import: Bulk import contacts from a CSV string (handles quoted fields)
+- tag: Add or remove a tag from a contact
+
+Use this to manage the business contact database — prospects, leads, customers, and inactive contacts.`;
+export const PROMPT = DESCRIPTION;