Tool / Integration Layer

LLM emits tool call JSON:
  { "tool": "google_search_console", "method": "getKeywordRankings", "input": { "siteUrl": "...", "query": "..." } }
          │
          ▼
Executor intercepts tool_call event
          │
          ▼
Permission check: is this tool in agent's toolNames[]?
          │
     ┌────┴────┐
    YES        NO
     │          │
     │      Reject: return error to LLM
     │
     ▼
Write action? Check approvals table for approved record
     │
 (read-only or approved)
     │
     ▼
Validate + sanitise input (Zod schema check; reject malformed LLM outputs before they reach integrations)
     │
     ▼
Call integration client method
     │
     ▼
Sanitise output (strip HTML from any string fields using DOMPurify; redact credentials before logging)
     │
     ▼
Log to tool_calls table (taskRunId, tool, method, input, output, status, durationMs)
     │
     ▼
Return result to LLM as tool result message

interface GoogleSearchConsoleClient {
  // Pull keyword rankings, impressions, clicks, CTR, position
  getKeywordRankings(params: {
    siteUrl:   string;
    startDate: string;   // YYYY-MM-DD
    endDate:   string;
    query?:    string;   // filter to specific keyword
    limit?:    number;
  }): Promise<SearchAnalyticsRow[]>;
 
  // Top landing pages by traffic
  getTopPages(params: {
    siteUrl:   string;
    startDate: string;
    endDate:   string;
    limit?:    number;
  }): Promise<PageAnalyticsRow[]>;
 
  // Index coverage issues
  getIndexingIssues(siteUrl: string): Promise<IndexingIssue[]>;
}

interface GoogleAdsClient {
  // Read
  getCampaignPerformance(customerId: string, dateRange: DateRange): Promise<CampaignStats[]>;
  getAdGroupPerformance(customerId: string, campaignId: string): Promise<AdGroupStats[]>;
  getAdPerformance(customerId: string, adGroupId: string): Promise<AdStats[]>;
  getKeywordPerformance(customerId: string, adGroupId: string): Promise<KeywordStats[]>;
 
  // Write (approval-gated)
  createResponsiveSearchAd(params: {
    customerId: string;
    adGroupId:  string;
    headlines:  string[];   // up to 15, max 30 chars each
    descriptions: string[]; // up to 4, max 90 chars each
    finalUrl:   string;
  }): Promise<CreatedAd>;
 
  pauseAd(customerId: string, adId: string): Promise<void>;
  updateBid(customerId: string, adGroupId: string, bidMicros: number): Promise<void>;
}

interface MetaAdsClient {
  // Read
  getCampaignInsights(adAccountId: string, dateRange: DateRange): Promise<CampaignInsights[]>;
  getAdSetInsights(adAccountId: string, campaignId: string): Promise<AdSetInsights[]>;
  getAdInsights(adAccountId: string, adSetId: string): Promise<AdInsights[]>;
  getPageInsights(pageId: string, metrics: string[]): Promise<PageInsights>;
  getAudienceInsights(adAccountId: string, targeting: TargetingSpec): Promise<AudienceSize>;
 
  // Write (approval-gated)
  createAd(params: {
    adAccountId: string;
    adSetId:     string;
    name:        string;
    creative: {
      primaryText: string;  // ≤ 125 chars
      headline:    string;  // ≤ 40 chars
      description: string;  // ≤ 30 chars
      imageUrl:    string;
      callToAction: string;
    };
  }): Promise<CreatedAd>;
 
  pauseAd(adAccountId: string, adId: string): Promise<void>;
}

interface GA4Client {
  // Core traffic report
  getTrafficReport(params: {
    propertyId: string;
    startDate:  string;
    endDate:    string;
    dimensions: string[];  // e.g. ['sessionDefaultChannelGroup', 'landingPage']
    metrics:    string[];  // e.g. ['sessions', 'conversions', 'bounceRate']
  }): Promise<GA4Report>;
 
  // Conversion funnel
  getConversionPaths(propertyId: string, dateRange: DateRange): Promise<ConversionPath[]>;
 
  // Real-time active users (for anomaly detection)
  getRealtimeData(propertyId: string): Promise<RealtimeData>;
}

interface SEMrushClient {
  getKeywordOverview(keyword: string, database: string): Promise<KeywordOverview>;
  getKeywordIdeas(seed: string, database: string, limit?: number): Promise<KeywordIdea[]>;
  getDomainOrganicKeywords(domain: string, database: string): Promise<OrganicKeyword[]>;
  getCompetitorDomains(domain: string): Promise<CompetitorDomain[]>;
  getBacklinkReport(domain: string): Promise<BacklinkReport>;
}

interface AhrefsClient {
  getDomainRating(target: string): Promise<DomainRating>;
  getBacklinks(target: string, limit?: number): Promise<Backlink[]>;
  getOrganicKeywords(target: string, country: string): Promise<OrganicKeyword[]>;
  getTopPages(target: string): Promise<TopPage[]>;
}

interface DataForSEOClient {
  // Check if a specific backlink is live
  checkBacklinkLive(targetUrl: string, sourceUrl: string): Promise<BacklinkLiveStatus>;
 
  // Bulk check multiple backlinks
  checkBacklinksBulk(links: Array<{ targetUrl: string; sourceUrl: string }>): Promise<BacklinkLiveStatus[]>;
 
  // Get full backlink profile for a domain
  getDomainBacklinks(domain: string, filters?: BacklinkFilters): Promise<DomainBacklink[]>;
}
 
interface BacklinkLiveStatus {
  targetUrl:    string;
  sourceUrl:    string;
  isLive:       boolean;    // Is the link currently present in the source page?
  isIndexed:    boolean;    // Is the source page indexed by Google?
  anchorText?:  string;
  linkType?:    'dofollow' | 'nofollow' | 'ugc' | 'sponsored';
  domainRating?: number;
  lastSeenOn?:  Date;
}

interface WordPressClient {
  createPost(params: {
    siteUrl:    string;
    title:      string;
    content:    string;  // HTML
    status:     'draft' | 'publish';
    categories: string[];
    tags:       string[];
    metaTitle?: string;
    metaDescription?: string;
    featuredImageUrl?: string;
  }): Promise<CreatedPost>;
 
  updatePost(siteUrl: string, postId: number, fields: Partial<PostFields>): Promise<void>;
}

interface MailchimpClient {
  createCampaign(params: {
    listId:      string;
    subject:     string;
    previewText: string;
    fromName:    string;
    replyTo:     string;
    htmlBody:    string;
    plainText:   string;
  }): Promise<CreatedCampaign>;
 
  scheduleCampaign(campaignId: string, sendAt: string): Promise<void>;
  // Note: never auto-sends; requires schedule action (also approval-gated)
}

interface KlaviyoClient {
  createEmailTemplate(params: {
    name:    string;
    html:    string;
  }): Promise<Template>;
 
  createCampaign(params: {
    listId:     string;
    templateId: string;
    subject:    string;
    fromEmail:  string;
    fromName:   string;
  }): Promise<Campaign>;
}

interface SlackClient {
  postMessage(params: {
    channel: string;    // e.g. '#client-acme' or channel ID
    text:    string;    // fallback plain text
    blocks?: SlackBlock[];  // rich message blocks
    attachments?: SlackAttachment[];
  }): Promise<void>;
 
  uploadFile(params: {
    channel:  string;
    content:  string;
    filename: string;
    title:    string;
  }): Promise<void>;
}

interface GoogleDocsClient {
  createDocument(params: {
    title:   string;
    content: string;  // Markdown converted to Docs format
    folderId?: string;
  }): Promise<{ docId: string; url: string }>;
 
  appendToDocument(docId: string, content: string): Promise<void>;
  shareDocument(docId: string, emailAddress: string, role: 'reader' | 'writer'): Promise<void>;
}

interface BrowserClient {
  scrapePageText(url: string): Promise<string>;
  scrapePageStructure(url: string): Promise<{ headings: string[]; links: string[]; metaTags: Record<string, string> }>;
  captureScreenshot(url: string): Promise<Buffer>;  // PNG
  scrapeMultiplePages(urls: string[], selector?: string): Promise<ScrapedPage[]>;
}

interface ReportBlockerInput {
  blockerType:       'channel_auth_expired'
                   | 'missing_integration'
                   | 'insufficient_data'
                   | 'api_unavailable'
                   | 'needs_human_input';
  message:           string;  // Clear explanation: what is blocked + what action resolves it
  channelId?:        string;  // Required when blockerType === 'channel_auth_expired'
  integrationName?:  string;  // Required when blockerType === 'missing_integration'
}

{
  "tool": "report_blocker",
  "input": {
    "blockerType": "channel_auth_expired",
    "message": "Google Search Console OAuth token is expired. Re-authenticate GSC in Settings → Channels to allow keyword ranking data to be fetched.",
    "channelId": "ch_abc123"
  }
}

{
  "status": "blocked",
  "message": "Your task has been suspended and a resolution task created in the DM Portal. You will be re-dispatched once the blocker is resolved."
}

interface CreateSubtaskInput {
  assigneeType:    'agent' | 'human';
  agentRole?:      AgentRole;           // required if assigneeType === 'agent'
  humanRole?:      'reviewer' | 'admin'; // required if assigneeType === 'human'
  taskName:        string;              // short label shown in the DM Portal and activity list
  taskDescription: string;             // full brief for the assignee — be specific
  blocking?:       boolean;            // default true — current activity suspends until done
  priority?:       'normal' | 'high';  // default 'normal'
}

// blocking: true
{ "status": "subtask_created", "subtaskId": "act_abc123",
  "message": "Subtask created and assigned to seo-specialist. Your task is suspended until it completes." }
 
// blocking: false
{ "status": "subtask_created", "subtaskId": "act_abc123",
  "message": "Subtask created. Continue your current task — the subtask runs in parallel." }

{
  "tool": "create_subtask",
  "input": {
    "assigneeType": "agent",
    "agentRole": "content-researcher",
    "taskName": "Research competitor blog topics for Acme Corp",
    "taskDescription": "Scrape the top 5 blog posts from acmecorp-competitor.com and identify the 10 most common topics covered. Return a structured list with topic, approximate word count, and primary keyword for each post.",
    "blocking": true,
    "priority": "normal"
  }
}

interface RequestHumanReviewInput {
  reviewTitle:   string;    // label shown in the DM Portal inbox
  content:       string;    // the work/draft to review (Markdown)
  instructions:  string;    // what the reviewer should evaluate and decide
  options?:      string[];  // if the reviewer must choose between options
                            // e.g. ['Proceed with approach A', 'Proceed with approach B']
}

{ "status": "review_requested",
  "message": "Review requested. Your task is paused. Resume after the reviewer responds." }

{
  "tool": "request_human_review",
  "input": {
    "reviewTitle": "Tone check: Blog post intro for Acme Corp",
    "content": "## Draft intro (300 words)\n\nAcme Corp has been building...",
    "instructions": "Please confirm the tone is right for this client before I write the full 2,000-word article. Specifically: is the level of formality correct, and should I lead with the problem or the solution?"
  }
}

interface ReassignTaskInput {
  assigneeType: 'agent' | 'human';
  agentRole?:   AgentRole;            // required if assigneeType === 'agent'
  humanRole?:   'reviewer' | 'admin'; // required if assigneeType === 'human'
  reason:       string;               // why this task needs a different assignee
}

{ "status": "reassigned",
  "message": "Task reassigned to seo-specialist. Your activity is now closed." }

{
  "tool": "reassign_task",
  "input": {
    "assigneeType": "agent",
    "agentRole": "seo-specialist",
    "reason": "This task requests a technical SEO audit (Core Web Vitals, crawl errors, schema markup). This is SEO Specialist scope, not Copywriter scope."
  }
}

interface AddCommentInput {
  body:      string;     // Markdown — supports @mentions (see below)
  internal?: boolean;    // default false; if true, hidden from tenant Dashboard (DM Portal + Manage only)
}

{ "status": "comment_added", "commentId": "cmt_xyz789" }

{
  "tool": "add_comment",
  "input": {
    "body": "Completed keyword research. Note: the primary keyword 'digital marketing agency london' has very high competition (KD 78). I've included 3 lower-competition alternatives in the brief. @human:reviewer — please confirm which direction to take before the Copywriter starts writing.",
    "internal": false
  }
}

CREATE TABLE activity_comments (
  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  activity_id   UUID NOT NULL REFERENCES activities(id),
  tenant_id     UUID NOT NULL REFERENCES tenants(id),
  author_type   VARCHAR(10) NOT NULL,   -- 'agent' | 'human'
  agent_role    VARCHAR(100),           -- set when author_type = 'agent'
  user_id       UUID REFERENCES users(id),  -- set when author_type = 'human'
  body          TEXT NOT NULL,          -- Markdown
  internal      BOOLEAN DEFAULT FALSE,
  created_at    TIMESTAMPTZ DEFAULT NOW()
);
 
CREATE INDEX ON activity_comments(activity_id);
CREATE INDEX ON activity_comments(tenant_id, created_at);

interface CreateApprovalInput {
  type:                 ApprovalType;
  // 'content_direction' | 'brand_direction' | 'strategy_change'
  // | 'budget_authorization' | 'content_review' | 'channel_action'
 
  title:                string;     // short label shown in DM Portal approval inbox
  description:          string;     // full context for the reviewer — what are they deciding?
 
  riskLevel?:           'low' | 'medium' | 'high';
                                    // default derived from type (see governance-guardrails.md)
 
  linkedActivityIds?:   string[];   // activities to block until this approval resolves
                                    // can be empty — approval blocks only the calling activity
 
  blockCurrentActivity?: boolean;   // also suspend the calling agent's activity; default true
 
  options?:             string[];   // if the reviewer must choose between named options
                                    // e.g. ['Proceed with formal tone', 'Proceed with casual tone']
 
  expiresInHours?:      number;     // override default expiry window
}

{
  "status": "approval_created",
  "approvalId": "apv_abc123",
  "message": "Approval created. 10 activities suspended until resolved by a reviewer."
}

{
  "tool": "create_approval",
  "input": {
    "type": "brand_direction",
    "title": "Approve tone direction for April social campaign",
    "description": "The April social calendar covers a product launch. I need a direction decision before writing 12 posts:\n\n- **Option A (Professional):** Focus on product specs, B2B language, LinkedIn-first\n- **Option B (Conversational):** Benefit-led, casual tone, Instagram-first\n\nThis decision will be applied to all 12 posts in the April campaign.",
    "riskLevel": "medium",
    "linkedActivityIds": ["act_001", "act_002", "act_003", "..."],
    "blockCurrentActivity": true,
    "options": [
      "Option A — Professional / B2B tone",
      "Option B — Conversational / Instagram-first tone"
    ]
  }
}

{
  "tool": "create_approval",
  "input": {
    "type": "budget_authorization",
    "title": "Authorize SEMrush API spend for competitor gap analysis",
    "description": "The competitor gap analysis requires approximately 200 SEMrush API rows (~$0.40 at current usage rate). This is within the monthly tool budget but I want explicit authorization before proceeding as the client is on a cost-sensitive plan.",
    "riskLevel": "low",
    "blockCurrentActivity": true
  }
}

class RateLimitedClient<T extends object> {
  constructor(private client: T, private limiter: Bottleneck) {}
 
  // Proxies all method calls through the limiter
  wrap(): T { /* Proxy pattern */ }
}
 
// Example: Google Search Console — 20 req/s
const gscClient = new RateLimitedClient(
  new GoogleSearchConsoleClient(credentials),
  new Bottleneck({ reservoir: 20, reservoirRefreshAmount: 20, reservoirRefreshInterval: 1000 })
).wrap();

integrations/
├── src/
│   ├── google-search-console/
│   │   ├── client.ts
│   │   ├── schema.ts         # JSON schema for LLM tool invocation
│   │   └── types.ts
│   ├── google-ads/
│   ├── meta-ads/
│   ├── ga4/
│   ├── semrush/
│   ├── ahrefs/
│   ├── dataforseo/           # Backlink live/indexed status checker
│   ├── wordpress/
│   ├── mailchimp/
│   ├── klaviyo/
│   ├── slack/
│   ├── google-docs/
│   ├── browser/              # Playwright wrapper
│   ├── control-plane/
│   │   ├── report-blocker.ts     # report_blocker
│   │   ├── create-subtask.ts     # create_subtask
│   │   ├── create-approval.ts    # create_approval
│   │   ├── request-review.ts     # request_human_review
│   │   ├── reassign-task.ts      # reassign_task
│   │   ├── add-comment.ts        # add_comment
│   │   └── schema.ts             # JSON schemas for all control plane tools
│   ├── rate-limiter.ts       # RateLimitedClient wrapper
│   ├── tool-dispatcher.ts    # Routes LLM tool calls to correct client or control plane
│   └── index.ts
└── package.json