Summary

• Knowledge base connector (helpscout): syncs Help Scout conversations and their threads into a knowledge base. Optional inbox (selector + manual ID), status, tag filter, include/exclude internal notes, and a max-conversations cap (default 500, max 5000). Listing returns deferred stubs whose hash comes from listing fields (thread count, status, timestamps, preview, tags), so only changed conversations are re-fetched; a cap that hides conversations marks the listing capped so deletions never reconcile against a partial set. Content is plain text (HTML stripped, line items skipped) ordered by time; tags map to status, tags, customer email, assignee, created date, and thread count. Works with both the OAuth and the app-credential connection
• Auto-registered webhook triggers: every Help Scout trigger now takes the Help Scout account (OAuth) plus an optional inbox. Deploy creates the Help Scout webhook with the trigger's events and a generated 40-character signing secret (externalId/webhookSecret stay system-managed); undeploy deletes it. The catch-all trigger subscribes to all 12 supported events. Replaces the manual paste-the-URL-and-secret setup
• 12 more tools (37 total): update conversation custom fields + list inbox custom fields, snooze/unsnooze, list/get saved replies, update customer properties + list property definitions, add customer message (customer thread), change conversation customer, list/get organizations; Update Customer can also add an email or phone
• Assignee picker lists users and teams (helpscout.assignees replaces helpscout.users; teams share the user ID space)
• Validation round (validate-trigger / validate-integration / validate-connector): webhook-create errors show Help Scout's reason, pinned payloadVersion: 'V2', "All Events" catch-all, no inbox filter on customer triggers, traceable webhook labels, Location fallback for the webhook ID; connector marks reconciliation unsafe when the result total shifts mid-scan, bounds the scan, adds Last Updated, skips spam/drafts/merged conversations, contentConcurrency: 3; tool output constants moved to types.ts so generated docs list each tool's own outputs; removal migration for the retired webhookSecret trigger field
• helpscout-errors explains Help Scout's empty-body 404s and is now explicitOnly, so the fallback chain never applies it to other services
• Docs intro updated for the connector and the new trigger setup

Type of Change

• New feature

Testing

Live against a real Help Scout account, through a local Sim on this branch:

• Credentials: app credential created through POST /api/v2/credentials (connect-time /users/me verification, display name from the verified user; wrong secret rejected with invalid_credentials); browser OAuth connect, token resolution through the credential service, forced refresh with refresh-token rotation persisted
• Selectors: inbox and user selectors through /api/v2/selectors/list|get with both credentials; missing credential rejected
• Workflow execution: deployed workflow of six Help Scout blocks run through the executor, alternating OAuth and app credentials: get current user, list inboxes, create conversation (inbox from the selector value), add note via <block.id> and <block.user.firstName> references with the status dropdown mapped, get with threads, delete
• Triggers: deploy created the Help Scout webhook (verified via API: convo.created, inbox filter, V2 payload); real Help Scout delivery through the tunnel hit /api/webhooks/trigger/<path>, passed signature verification with the generated secret, queued, and ran the workflow, whose downstream block posted a note back with resolved trigger outputs; undeploy deleted the webhook (404). Catch-all trigger subscribes to all 12 events; an app credential is refused at deploy with no partial registration
• Connector: created through /api/v2/knowledge/{id}/connectors (OAuth and app credential); initial sync stored the conversation with correct text and tag slots; a new customer reply re-synced exactly that document; deleting the conversation in Help Scout removed it on the next sync. Embedding failed locally only because the local OpenAI key is invalid
• New tools live-checked against the account: custom fields, saved replies, organizations (with counts), properties error surfacing, customer email/phone add, customer message, snooze/unsnooze round trip, change customer; assignee picker paging users then teams; a note-only change moves the connector hash; list vs single-conversation hash parity with multiple tags
• Direct live checks: all 25 tools through the shared transport (24 exercised; move needs a second inbox), 10 real webhook deliveries through the handler, 14 connector checks (hash parity between listing and fetch, cap flag, notes toggle, change detection, deleted → null)
• lib/webhooks/providers/helpscout.test.ts, blocks/blocks.test.ts, connector suite tests, selector manifest; check-block-registry, canvas sentences, docs, integration catalog, deployment config, fork-dependent coverage, client boundary, source conventions, utils, comment hygiene, CLI docs, icon precision, biome

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing (new tests pass the test-audit authoring gate)
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)