feat(captain): align custom tool limits

docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md

@@ -49,11 +49,11 @@ Hermes task landing checklist:
 
 ## Current Baseline
 
-- Current tracking checkpoint: 2026-06-07 P3.104 Captain custom tools feature gate, prepared as `feat(captain): gate custom tools`.
-- Latest implementation checkpoint: this checkpoint, prepared as `feat(captain): gate custom tools`.
-- Latest documentation/tooling checkpoint: this tracker update records Chatwoot-compatible feature gating for Captain custom tools.
+- Current tracking checkpoint: 2026-06-07 P3.105 Captain custom tool create limits and slug parity, prepared as `feat(captain): align custom tool limits`.
+- Latest implementation checkpoint: this checkpoint, prepared as `feat(captain): align custom tool limits`.
+- Latest documentation/tooling checkpoint: this tracker update records Chatwoot-compatible Captain custom-tool create caps and generated slugs.
 - Plan landing status: complete for the current known Hermes plans and user-confirmed scope. Future work should update this file directly instead of opening a parallel tracker.
-- Worktree status at this implementation checkpoint: Captain custom tool index/show/create/update/delete/test routes now enforce Chatwoot's `custom_tools` or `captain_integration_v2` account feature gate and return the raw forbidden payload when disabled. This retains P5.3i CSAT survey indexing, P5.3h provider webhook indexing, P5.3g message delivery indexing, P5.3f automation action indexing, P5.3e conversation maintenance indexing, P5.3d conversation bulk-action indexing, P5.3c contact label search indexing, P3.103 contact bulk-action parity, and prior checkpoints. Live API/browser/enterprise smoke still needs the full PostgreSQL/Redis/Meilisearch/GoChat/Vite/Chrome stack.
+- Worktree status at this implementation checkpoint: Captain custom-tool create now enforces Chatwoot's 15-tools-per-account cap, returns raw `422 { error: "You can create a maximum of 15 custom tools per account" }` when exceeded, generates default `custom_` underscore slugs capped at 64 characters, appends six-character lowercase alphanumeric collision suffixes, and keeps custom-tool uniqueness scoped by account like the reference schema. This retains P3.104 Captain custom tool feature gating, P5.3i CSAT survey indexing, P5.3h provider webhook indexing, P5.3g message delivery indexing, P5.3f automation action indexing, P5.3e conversation maintenance indexing, P5.3d conversation bulk-action indexing, P5.3c contact label search indexing, P3.103 contact bulk-action parity, and prior checkpoints. Live API/browser/enterprise smoke still needs the full PostgreSQL/Redis/Meilisearch/GoChat/Vite/Chrome stack.
 - Next executable implementation checkpoint: continue Phase 2/3 drift audit for the next reused-frontend mismatch, or run B12 live smoke when the full PostgreSQL/Redis/Meilisearch/GoChat/Vite/Chrome stack is available. Re-run Phase 6 placeholder audit after future route/smoke changes.
 - `go test ./...` passes when run outside the restricted socket sandbox for the latest implementation baseline; the latest docs/tooling checkpoint verified `scripts/parity_frontend_smoke.sh --check` with workspace-local temp/cache dirs after `/tmp` was full.
 - Route dump succeeds with `972` registered routes after enterprise account route tracking.
@@ -156,6 +156,7 @@ This table is the shortest authoritative handoff view. If an older lower section
 
 | Priority | Workstream | Current state | Next checkpoint | Commit close rule |
 | --- | --- | --- | --- | --- |
+| 0 | P3.105 Captain custom tool create limits and slug parity | Implemented for reused Captain custom-tool creation: GoChat now mirrors `Captain::CustomTool` by allowing at most 15 custom tools per account, returning raw `422 { error: "You can create a maximum of 15 custom tools per account" }` when the cap is exceeded, generating default slugs as `custom_` + parameterized title with underscore separators, capping generated slugs at 64 characters, adding `_xxxxxx` lowercase alphanumeric suffixes on same-account collisions, and keeping the uniqueness boundary scoped to `(account_id, slug)` like the Chatwoot schema. | Keep in Review; reopen from B12 Captain custom-tools smoke or fresh reference evidence for exact Rails `parameterize` locale transliteration, concurrent account-row locking, auth-config administrator-only serialization, enum/schema validation response shape, or slug-generation exhaustion wording beyond the inspected model/controller contract. | Focused Captain custom-tool/resource tests passed; full `go test ./...` passed outside the restricted socket sandbox; `git diff --check` passed. No route artifacts change. |
 | 0 | P3.104 Captain custom tools feature gate | Implemented for reused Captain custom-tool screens: `GET/POST/PUT/DELETE /api/v1/accounts/:account_id/captain/custom_tools` and `POST /captain/custom_tools/test` now enforce the inspected Chatwoot `ensure_custom_tools_enabled` gate. Accounts must have `custom_tools` or `captain_integration_v2` enabled; disabled accounts receive raw `403 { error: "Custom tools are not enabled for this account" }`. Bootstrap passes the account repository into the custom-tool service so normal app routes use persisted account feature flags. | Keep in Review; reopen from B12 Captain custom-tools smoke or fresh reference evidence for exact authorization ordering, feature-flag defaults, custom-tool limit behavior, or request execution drift beyond the inspected controller/frontend contract. | Focused Captain custom-tool/resource tests passed; full `go test ./...` passed outside the restricted socket sandbox; `git diff --check` passed. No route artifacts change. |
 | 0 | P5.3i CSAT survey search indexing | Implemented for Meilisearch CSAT parity: `CsatSurveyService` reindexes CSAT survey messages and parent conversations after resolved-conversation survey creation and public survey submission; `CsatSurveyListener` propagates the durable search indexer into synchronous and queued `csat:survey_send` paths and reindexes message/conversation documents after `message.updated` CSAT submitted-value processing; bootstrap wires both the public CSAT handler service and event listener to the durable search indexer. | Keep in Review; reopen from live Meilisearch gate, CSAT smoke, or a fresh CSAT mutation path that changes searchable message/conversation fields without indexing. | Focused CSAT survey service/listener search tests passed; full `go test ./...` passed outside the restricted socket sandbox; `git diff --check` passed. No route artifacts change. |
 | 0 | P5.3h provider webhook search indexing | Implemented for Meilisearch provider-webhook parity: `IncomingPersister` indexes contacts, conversations, and messages after non-duplicate incoming persistence; indexes direct and durable provider message status updates; indexes every message touched by contact-wide status/read receipts; Facebook, Telegram, WhatsApp, TikTok, LINE, and Twilio webhook handlers receive the durable search indexer from bootstrap. | Keep in Review; reopen from live Meilisearch gate, provider webhook smoke, or a fresh incoming/status mutation path that changes searchable contact/conversation/message fields without indexing. | Focused webhook persister search tests passed; full `go test ./...` passed outside the restricted socket sandbox; `git diff --check` passed. No route artifacts change. |
@@ -400,6 +401,7 @@ This ledger records the committed parity checkpoints that future slices should b
 
 | Commit | Scope | Verification summary | Follow-up state |
 | --- | --- | --- | --- |
+| `feat(captain): align custom tool limits` | Advances P3.105 with Chatwoot Captain custom-tool create limits and generated slug parity. GoChat now enforces the 15-tools-per-account cap, returns the inspected limit error as raw `422`, generates default `custom_` underscore slugs capped at 64 characters, adds six-character lowercase alphanumeric collision suffixes, and makes the GORM model uniqueness boundary match the reference `(account_id, slug)` schema. | Focused Captain custom-tool/resource tests passed; full `go test ./...` passed outside the restricted socket sandbox; `git diff --check` passed. No route artifacts change. | Move P3.105 to Review; continue Captain custom-tool validation/administrator serialization drift, Phase 2/3 audit, Phase 6 placeholder audit, or B12 live smoke. |
 | `feat(search): index conversation maintenance` | Advances P5.3/B6 for mandatory Meilisearch background-maintenance parity. Scheduled snooze reopen and account auto-resolution now reindex updated conversations, message-status maintenance reindexes changed messages plus the parent conversation, and bootstrap registers search-aware maintenance handlers after durable search indexing is wired. | Focused conversation maintenance search tests passed; full `go test ./...` passed outside the restricted socket sandbox; `git diff --check` passed. No route artifacts change. | Move P5.3e to Review; continue Phase 2/3 drift audit, Phase 6 placeholder audit, or B12 live smoke. |
 | `feat(search): index conversation bulk actions` | Advances P5.3/B6 for mandatory Meilisearch conversation bulk-action parity. Account conversation bulk-action worker replay now reindexes every updated conversation after bulk status/team/assignee/snooze/label changes, while the app registers the search-aware runner after durable search indexing is wired. | Focused conversation bulk-action search test passed; full `go test ./...` passed outside the restricted socket sandbox; `git diff --check` passed. No route artifacts change. | Move P5.3d to Review; continue Phase 2/3 drift audit, Phase 6 placeholder audit, or B12 live smoke. |
 | `feat(search): index contact labels` | Advances P5.3/B6 for mandatory Meilisearch contact label parity. Contact documents now carry label arrays, durable contact index replay preloads current label assignments, `ContactService.UpdateLabels` reindexes contacts after replacement, and contact bulk-action add/remove/delete jobs enqueue search index/delete follow-up jobs through the durable indexer. | Focused service/search tests passed; full `go test ./...` passed outside the restricted socket sandbox; `git diff --check` passed. No route artifacts change. | Move P5.3c to Review; continue Phase 2/3 drift audit, Phase 6 placeholder audit, or B12 live smoke. |
@@ -2814,3 +2816,4 @@ Verification milestone gates:
 - 2026-06-07: P5.3h provider webhook search-index checkpoint prepared as `feat(search): index provider webhooks`; audited GoChat `IncomingPersister` incoming persistence, provider message status, contact-wide read receipt jobs, and provider webhook handler bootstrap wiring against the P5.3 Meilisearch durability contract. GoChat now indexes contacts/conversations/messages after provider incoming message persistence, skips duplicate indexing, indexes durable incoming replay, indexes direct/durable provider delivery status updates, indexes every contact-wide read-receipt message mutation, and wires Facebook/Telegram/WhatsApp/TikTok/LINE/Twilio webhook handlers to the durable search indexer. Focused webhook persister search tests passed; full `go test ./...` passed outside the restricted socket sandbox; `git diff --check` passed. No route artifacts change.
 - 2026-06-07: P5.3i CSAT survey search-index checkpoint prepared as `feat(search): index csat surveys`; audited GoChat CSAT survey creation/submission mutation paths against the P5.3 Meilisearch durability contract. GoChat now reindexes CSAT survey messages and parent conversations after resolved-conversation survey sends, durable `csat:survey_send` replay, public CSAT survey submissions, and `message.updated` submitted-value processing; bootstrap wires the public CSAT survey service and CSAT event listener to the durable search indexer. Focused CSAT survey service/listener search tests passed; full `go test ./...` passed outside the restricted socket sandbox after the expected sandbox-only local socket failures; `git diff --check` passed. No route artifacts change.
 - 2026-06-07: P3.104 Captain custom-tools feature-gate checkpoint prepared as `feat(captain): gate custom tools`; audited Chatwoot `Api::V1::Accounts::Captain::CustomToolsController#ensure_custom_tools_enabled`, reused dashboard `api/captain/customTools.js`, and GoChat Captain custom-tool routes. GoChat now gates custom-tool index/show/create/update/delete/test routes on persisted account `custom_tools` or `captain_integration_v2` feature flags, returns raw `403 { error: "Custom tools are not enabled for this account" }` for disabled accounts, and wires the account repository into the production Captain custom-tool service. Focused Captain custom-tool/resource handler tests passed; full `go test ./...` passed outside the restricted socket sandbox; `git diff --check` passed. No route artifacts change.
+- 2026-06-07: P3.105 Captain custom-tool create limits and slug checkpoint prepared as `feat(captain): align custom tool limits`; audited Chatwoot `Captain::CustomTool` constants/callbacks, `CustomToolsController#create` limit rescue, and `_custom_tool.json.jbuilder`. GoChat now enforces the 15-tools-per-account cap, returns raw `422` with the reference limit message, generates omitted slugs as `custom_` + underscore-parameterized title, caps generated slugs at 64 characters, appends `_xxxxxx` lowercase alphanumeric suffixes on account-scoped collisions, and aligns the GORM uniqueness tag with the reference `(account_id, slug)` index. Focused Captain custom-tool/resource tests passed; full `go test ./...` passed outside the restricted socket sandbox; `git diff --check` passed. No route artifacts change.

internal/handler/api/v1/captain_custom_tool_crud_handler_test.go

@@ -5,7 +5,9 @@ import (
 	"encoding/json"
 	"net/http"
 	"net/http/httptest"
+	"regexp"
 	"strconv"
+	"strings"
 	"testing"
 
 	"github.com/gin-gonic/gin"
@@ -163,6 +165,87 @@ func (s *CaptainCustomToolCRUDTestSuite) TestCreate_默认GET方法() {
 	assert.Equal(s.T(), "GET", resp["http_method"]) // default HTTP method
 }
 
+func (s *CaptainCustomToolCRUDTestSuite) TestCreate_省略Slug时使用ChatwootCustom前缀和下划线() {
+	body := map[string]interface{}{
+		"custom_tool": map[string]interface{}{
+			"title":        "Lookup Order",
+			"endpoint_url": "https://example.com/orders",
+		},
+	}
+
+	w := s.makeRequest("POST", s.accountPath()+"/captain/custom_tools/", body)
+	assert.Equal(s.T(), http.StatusOK, w.Code)
+
+	var resp map[string]interface{}
+	s.Require().NoError(json.Unmarshal(w.Body.Bytes(), &resp))
+	assert.Equal(s.T(), "custom_lookup_order", resp["slug"])
+}
+
+func (s *CaptainCustomToolCRUDTestSuite) TestCreate_重复标题Slug追加随机后缀() {
+	body := map[string]interface{}{
+		"custom_tool": map[string]interface{}{
+			"title":        "Lookup Order",
+			"endpoint_url": "https://example.com/orders",
+		},
+	}
+
+	w1 := s.makeRequest("POST", s.accountPath()+"/captain/custom_tools/", body)
+	s.Require().Equal(http.StatusOK, w1.Code)
+	w2 := s.makeRequest("POST", s.accountPath()+"/captain/custom_tools/", body)
+	s.Require().Equal(http.StatusOK, w2.Code)
+
+	var first, second map[string]interface{}
+	s.Require().NoError(json.Unmarshal(w1.Body.Bytes(), &first))
+	s.Require().NoError(json.Unmarshal(w2.Body.Bytes(), &second))
+	assert.Equal(s.T(), "custom_lookup_order", first["slug"])
+	assert.NotEqual(s.T(), first["slug"], second["slug"])
+	assert.Regexp(s.T(), regexp.MustCompile(`^custom_lookup_order_[a-z0-9]{6}$`), second["slug"])
+}
+
+func (s *CaptainCustomToolCRUDTestSuite) TestCreate_生成Slug最长64字符() {
+	body := map[string]interface{}{
+		"custom_tool": map[string]interface{}{
+			"title":        strings.Repeat("Very Long Title ", 10),
+			"endpoint_url": "https://example.com/long",
+		},
+	}
+
+	w := s.makeRequest("POST", s.accountPath()+"/captain/custom_tools/", body)
+	assert.Equal(s.T(), http.StatusOK, w.Code)
+
+	var resp map[string]interface{}
+	s.Require().NoError(json.Unmarshal(w.Body.Bytes(), &resp))
+	slug := resp["slug"].(string)
+	assert.LessOrEqual(s.T(), len(slug), 64)
+	assert.True(s.T(), strings.HasPrefix(slug, "custom_"))
+}
+
+func (s *CaptainCustomToolCRUDTestSuite) TestCreate_超过每账户15个工具返回422() {
+	for i := 0; i < 15; i++ {
+		body := map[string]interface{}{
+			"custom_tool": map[string]interface{}{
+				"title":        "Limit Tool " + strconv.Itoa(i),
+				"slug":         "limit-tool-" + strconv.Itoa(i),
+				"endpoint_url": "https://example.com/limit" + strconv.Itoa(i),
+			},
+		}
+		w := s.makeRequest("POST", s.accountPath()+"/captain/custom_tools/", body)
+		s.Require().Equal(http.StatusOK, w.Code)
+	}
+
+	w := s.makeRequest("POST", s.accountPath()+"/captain/custom_tools/", map[string]interface{}{
+		"custom_tool": map[string]interface{}{
+			"title":        "One Too Many",
+			"endpoint_url": "https://example.com/too-many",
+		},
+	})
+
+	assert.Equal(s.T(), http.StatusUnprocessableEntity, w.Code)
+	var resp map[string]interface{}
+	s.Require().NoError(json.Unmarshal(w.Body.Bytes(), &resp))
+	assert.Equal(s.T(), "You can create a maximum of 15 custom tools per account", resp["error"])
+}
+
 func (s *CaptainCustomToolCRUDTestSuite) TestCreate_无效JSON返回400() {
 	// ShouldBindJSON 在 JSON 解析失败时返回 400
 	w := httptest.NewRecorder()

internal/handler/api/v1/captain_custom_tool_handler.go

@@ -1,6 +1,7 @@
 package v1
 
 import (
+	"errors"
 	"net/http"
 
 	"github.com/gin-gonic/gin"
@@ -42,6 +43,10 @@ func (h *CaptainCustomToolHandler) Create(c *gin.Context) {
 	tool, err := h.svc.Create(c.Request.Context(), accountID, &req)
 	if err != nil {
 		applogger.L().Errorf("Create captain custom tool: %v", err)
+		if errors.Is(err, service.ErrCaptainCustomToolLimitExceeded) {
+			c.JSON(http.StatusUnprocessableEntity, gin.H{"error": service.ErrCaptainCustomToolLimitExceeded.Error()})
+			return
+		}
 		response.AbortWithStatusError(c, http.StatusInternalServerError, response.ErrInternal, "failed to create custom tool")
 		return
 	}

internal/handler/api/v1/captain_resource_parity_handler_test.go

@@ -195,7 +195,7 @@ func TestCaptainCustomToolHandler_ChatwootToolPayloadsAndScope(t *testing.T) {
 	var created map[string]any
 	require.NoError(t, json.Unmarshal(w.Body.Bytes(), &created))
 	assert.NotContains(t, created, "success")
-	assert.Equal(t, "lookup-order", created["slug"])
+	assert.Equal(t, "custom_lookup_order", created["slug"])
 	assert.Equal(t, "POST", created["http_method"])
 	toolID := uint(created["id"].(float64))
 

internal/model/captain_models.go

@@ -251,9 +251,9 @@ func (CaptainScenario) TableName() string { return "captain_scenarios" }
 
 type CaptainCustomTool struct {
 	Base
-	AccountID        uint            `gorm:"index;not null" json:"account_id"`
+	AccountID        uint            `gorm:"index;uniqueIndex:idx_captain_custom_tools_account_slug,priority:1;not null" json:"account_id"`
 	Title            string          `gorm:"size:255;not null" json:"title"`
-	Slug             string          `gorm:"size:64;not null;uniqueIndex:idx_account_slug" json:"slug"`
+	Slug             string          `gorm:"size:64;not null;uniqueIndex:idx_captain_custom_tools_account_slug,priority:2" json:"slug"`
 	Description      string          `gorm:"type:text" json:"description,omitempty"`
 	EndpointURL      string          `gorm:"type:text;not null" json:"endpoint_url"`
 	HTTPMethod       string          `gorm:"size:10;default:GET;not null" json:"http_method"`

internal/service/captain_custom_tool_service.go

@@ -3,9 +3,12 @@ package service
 import (
 	"bytes"
 	"context"
+	"crypto/rand"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
+	"math/big"
 	"net/http"
 	"regexp"
 	"strings"
@@ -25,6 +28,14 @@ type CaptainCustomToolService struct {
 	httpClient  HTTPDoer
 }
 
+const (
+	maxCaptainCustomToolsPerAccount = 15
+	maxCaptainCustomToolSlugLength  = 64
+	customToolSlugCollisionSuffix   = 7
+)
+
+var ErrCaptainCustomToolLimitExceeded = errors.New("You can create a maximum of 15 custom tools per account")
+
 type HTTPDoer interface {
 	Do(req *http.Request) (*http.Response, error)
 }
@@ -89,6 +100,14 @@ type UpdateCustomToolRequest struct {
 
 // Create creates a new CaptainCustomTool.
 func (s *CaptainCustomToolService) Create(ctx context.Context, accountID uint, req *CreateCustomToolRequest) (*model.CaptainCustomTool, error) {
+	count, err := s.toolRepo.CountByAccount(ctx, accountID)
+	if err != nil {
+		return nil, fmt.Errorf("count custom tools: %w", err)
+	}
+	if count >= maxCaptainCustomToolsPerAccount {
+		return nil, ErrCaptainCustomToolLimitExceeded
+	}
+
 	// Default values
 	httpMethod := req.HTTPMethod
 	if httpMethod == "" {
@@ -100,7 +119,10 @@ func (s *CaptainCustomToolService) Create(ctx context.Context, accountID uint, r
 	}
 	slug := req.Slug
 	if slug == "" {
-		slug = customToolSlug(req.Title)
+		slug, err = s.uniqueCustomToolSlug(ctx, accountID, req.Title)
+		if err != nil {
+			return nil, err
+		}
 	}
 
 	tool := &model.CaptainCustomTool{
@@ -265,14 +287,54 @@ func applyCustomToolUpdate(tool *model.CaptainCustomTool, req *UpdateCustomToolR
 	}
 }
 
+func (s *CaptainCustomToolService) uniqueCustomToolSlug(ctx context.Context, accountID uint, title string) (string, error) {
+	baseSlug := customToolSlug(title)
+	if !s.customToolSlugExists(ctx, accountID, baseSlug) {
+		return baseSlug, nil
+	}
+
+	truncated := truncateString(baseSlug, maxCaptainCustomToolSlugLength-customToolSlugCollisionSuffix)
+	for i := 0; i < 5; i++ {
+		candidate := truncated + "_" + randomLowerAlphanumeric(6)
+		if !s.customToolSlugExists(ctx, accountID, candidate) {
+			return candidate, nil
+		}
+	}
+	return "", fmt.Errorf("slug generation failed")
+}
+
+func (s *CaptainCustomToolService) customToolSlugExists(ctx context.Context, accountID uint, slug string) bool {
+	_, err := s.toolRepo.GetBySlug(ctx, accountID, slug)
+	return err == nil
+}
+
 func customToolSlug(title string) string {
 	slug := strings.ToLower(strings.TrimSpace(title))
-	slug = regexp.MustCompile(`[^a-z0-9]+`).ReplaceAllString(slug, "-")
-	slug = strings.Trim(slug, "-")
-	if slug == "" {
-		return "custom-tool"
+	slug = regexp.MustCompile(`[^a-z0-9]+`).ReplaceAllString(slug, "_")
+	slug = strings.Trim(slug, "_")
+	return truncateString("custom_"+slug, maxCaptainCustomToolSlugLength)
+}
+
+func truncateString(value string, maxLen int) string {
+	if len(value) <= maxLen {
+		return value
 	}
-	return slug
+	return value[:maxLen]
+}
+
+func randomLowerAlphanumeric(length int) string {
+	const alphabet = "abcdefghijklmnopqrstuvwxyz0123456789"
+	var b strings.Builder
+	b.Grow(length)
+	for i := 0; i < length; i++ {
+		n, err := rand.Int(rand.Reader, big.NewInt(int64(len(alphabet))))
+		if err != nil {
+			b.WriteByte(alphabet[time.Now().UnixNano()%int64(len(alphabet))])
+			continue
+		}
+		b.WriteByte(alphabet[n.Int64()])
+	}
+	return b.String()
 }
 
 // --- Tool Execution ---