@sellable/mcp 0.1.419 → 0.1.421

package/dist/tools/setup-evergreen-campaigns.js

@@ -6,7 +6,7 @@ async function postSetupEvergreenCampaigns(body) {
 export const setupEvergreenCampaignsToolDefinitions = [
     {
         name: "setup_evergreen_campaigns",
-        description: "Evergreen campaign setup plan/verify command. Use plan mode first to inspect exact workspace/sender/campaign/table/source state and receive immutable lane packets. `selectedSenderIds` is a legacy shorthand for both scopes; prefer `postEngagerSenderIds` for the Post Engagers sender scope and `sharedSenderIds` for the shared lane sender scope when they differ. If a protected existing Post Engagers campaign must stay unchanged and the operator requested only shared lane execution, pass postEngagerSenderIds:[] and sharedSenderIds; do not include the protected active Post Engagers lane as a reuse packet because it can make the yolo plan non-autoExecutable. The command plans one Post Engagers lane per post-engager sender plus shared Signal Discovery and Shared Cold Fallback lanes for the shared sender set. yolo is only a parent-skill auto-execution hint for safe lane packets; pass yolo only in plan mode and never include yolo on mode:\"verify\" calls. This backend command remains read-only in plan mode and verifies receipts in verify mode. Package-backed prompt authority: the installed public wrapper can be the local Codex skill entrypoint, but lane workers must use get_subskill_prompt and get_subskill_asset for nested `$sellable:create-campaign`, create-campaign-v2, generate-messages, validation, and assets; nested filesystem prompt fallback is a failed UAT. Use mcp__sellable only for workspace selection and product mutations/readbacks. Do not use mcp__sellable_admin, direct DB, Prisma, SQL, built-in web search, browser search, web.run, or any external browsing/search tool as execution or research proof; if Sellable MCP research tools are insufficient, write a blocked receipt instead of browsing externally. Worker-local replans are read-only drift checks and must preserve the exact parent sender scopes, including postEngagerSenderIds:[] when intentionally empty and the exact sharedSenderIds array; if scope, planRevision, actionId, or laneKey drifts, stop with blocked:worker_plan_scope_drift before mutation. Each lane packet includes workerDispatch with acceptedRuntimes, rejectedRuntimes, requiresVisibleThreadOrDurableReceipt, receiptArtifactHint, receiptRunId, and receiptMustBeWrittenAfter; pre-existing receipts at old deterministic paths are stale and must not be used, so stop with blocked:stale_receipt_artifact if the receipt was not freshly written for the current receiptRunId. `multi_agent_v1.spawn_agent`/opaque spawn_agent is not accepted for mutating command proof unless the parent has visible thread or durable receipt proof. In local Codex, prefer `codex_app.list_projects` then `codex_app.create_thread` with a local project target; do not create a worktree for lane execution. If Codex app thread tools are unavailable but local Codex CLI is available, use durable streaming workers with `codex -a never -s danger-full-access exec -C <repo> -o <worker-final-file> -`; approval and sandbox flags must appear before `exec`, and current customer CLI installs reject `codex exec --ask-for-approval never` and `codex exec -a never`. When safe-yolo needs normal setup work, the parent skill may ask for bounded delegated approval: one approval over the current planRevision, selected action ids, caps, allowed side-effect classes, and stop conditions lets lane workers execute without per-substep approval while staying inside that packet. In exec/automation mode, do not call request_user_input; if yolo plan autoExecutable:false and no interactive approval can be received, stop with blocked:bounded_approval_unavailable_in_exec_mode before any mutation. Lane workers must explicitly load and use the installed `$sellable:create-campaign` wrapper as the nested workflow entrypoint, then load `create-campaign-v2` and `create-campaign-v2/core/flow.v2.json`; they must execute creation, source import, create-campaign workflow steps, generate-messages, sequence attachment, pause_campaign review-state transition when the current table is still DRAFT, and review readiness through that existing create-campaign workflow/subskills, then return receipts here for verification. Customer-visible verify receipts must set status:'succeeded' or status:'completed'; status:'passed', status:'pass', and status:'passed_with_warnings' are rejected as primary success statuses. Receipts must include createCampaignStepReceipt with setupPlanCall, createCampaignWorkflowReceipt, campaignBriefReceipt, sourceDecisionReceipt, filterDecisionReceipt, messageDraftingReceipt, reviewBatchReceipt, sequenceReceipt, and verifyCall nested inside createCampaignStepReceipt; top-level-only copies of those objects are not enough and are not promoted by verify. setupPlanCall must use canonical keys: planRevision, actionId, laneKey, workspaceId, senderIds, campaignId, tableId, createIntent. Do not use laneActionId, lanePacketActionId, delegatedPlanRevision, delegatedActionId, or requestedCall text as a substitute for those canonical fields. createCampaignWorkflowReceipt must include skillCommand:'$sellable:create-campaign', skillName:'create-campaign', wrapperSkillLoaded:true, workflowPromptName:'create-campaign-v2', workflowPromptLoadedToHasMoreFalse:true, workflowAssetPath:'create-campaign-v2/core/flow.v2.json', workflowAssetLoaded:true, workerRuntime, workerThreadId or receiptArtifactPath, durableReceiptWritten when using a receipt file, and notAdHoc:true. messageDraftingReceipt must use exactly statusSource:'branch' or statusSource:'packaged-generate-messages-worker'; descriptive aliases such as statusSource:'package-readback-local-thread' are rejected. It must include proof that generate-messages was loaded, start_campaign_message_preparation/get_campaign_message_preparation_status ran when the packaged worker path is used, validationResult:'passed', a passed qualityReview, and at least 3 concrete sampleMessages with rowId, generatedMessageText, verdict, and issues; Do not substitute `message` for `generatedMessageText`; Do not substitute `passVerdict` for `verdict`. Before writing durable receipts, run a receipt self-check: top-level `planRevision`, `actionId`, `laneKey`, `laneType`, `workspaceId`, and `senderIds` must exist; if the self-check fails, fix the receipt before ending. Use start_campaign_message_preparation with approvalMode:\"mark_ready\" only for evergreen setup. Never call `start_campaign_message_preparation` with `approvalMode:\"approve\"`; approve exactly one semantic Approved cell through select_campaign_cells/update_cell and final proof must show approvedGeneratedMessageCount exactly 1. Shared Cold Fallback samples with a standalone name followed by 'Hey there' are rejected. This command does not launch campaigns, does not schedule sends, does not assign scheduler-owned send fields, does not raw-write campaign status, does not archive/delete cleanup targets, and does not spend paid credits.",
+        description: "Evergreen campaign setup plan/verify command. Use plan mode first to inspect exact workspace/sender/campaign/table/source state and receive immutable lane packets. `selectedSenderIds` is a legacy shorthand for both scopes; prefer `postEngagerSenderIds` for the Post Engagers sender scope and `sharedSenderIds` for the shared lane sender scope when they differ. If a protected existing Post Engagers campaign must stay unchanged and the operator requested only shared lane execution, pass postEngagerSenderIds:[] and sharedSenderIds; do not include the protected active Post Engagers lane as a reuse packet because it can make the yolo plan non-autoExecutable. The command plans one Post Engagers lane per post-engager sender plus shared Signal Discovery and Shared Cold Fallback lanes for the shared sender set. yolo is only a parent-skill auto-execution hint for safe lane packets; pass yolo only in plan mode and never include yolo on mode:\"verify\" calls. This backend command remains read-only in plan mode and verifies receipts in verify mode. Package-backed prompt authority: the installed public wrapper can be the local Codex skill entrypoint, but lane workers must use get_subskill_prompt and get_subskill_asset for nested `$sellable:create-campaign`, create-campaign-v2, generate-messages, validation, and assets; nested filesystem prompt fallback is a failed UAT. Use mcp__sellable only for workspace selection and product mutations/readbacks. Do not use mcp__sellable_admin, direct DB, Prisma, SQL, built-in web search, browser search, web.run, or any external browsing/search tool as execution or research proof; if Sellable MCP research tools are insufficient, write a blocked receipt instead of browsing externally. Worker-local replans are read-only drift checks and must preserve the exact parent sender scopes, including postEngagerSenderIds:[] when intentionally empty and the exact sharedSenderIds array; if scope, planRevision, actionId, or laneKey drifts, stop with blocked:worker_plan_scope_drift before mutation. Each lane packet includes workerDispatch with acceptedRuntimes, rejectedRuntimes, requiresVisibleThreadOrDurableReceipt, receiptArtifactHint, receiptRunId, and receiptMustBeWrittenAfter; pre-existing receipts at old deterministic paths are stale and must not be used, so stop with blocked:stale_receipt_artifact if the receipt was not freshly written for the current receiptRunId. `multi_agent_v1.spawn_agent`/opaque spawn_agent is not accepted for mutating command proof unless the parent has visible thread or durable receipt proof. In local Codex, prefer `codex_app.list_projects` then `codex_app.create_thread` with a local project target; do not create a worktree for lane execution. If Codex app thread tools are unavailable but local Codex CLI is available, use durable streaming workers with `codex -a never -s danger-full-access exec -C <repo> -o <worker-final-file> -`; approval and sandbox flags must appear before `exec`, and current customer CLI installs reject `codex exec --ask-for-approval never` and `codex exec -a never`. Plan responses include approvalSummary; render approvalSummary when asking for bounded delegated approval because it explicitly lists campaignsToCreate, campaignsToUpdate, campaignsToVerifyOnly, campaignsLeftUntouched, attachedSenders, selectedActionIds, allowedSideEffects, forbiddenSideEffects, blockers, and approvalQuestion. When safe-yolo needs normal setup work, the parent skill may ask for bounded delegated approval: one approval over the current planRevision, selected action ids, caps, allowed side-effect classes, and stop conditions lets lane workers execute without per-substep approval while staying inside that packet. In exec/automation mode, do not call request_user_input; if yolo plan autoExecutable:false and no interactive approval can be received, stop with blocked:bounded_approval_unavailable_in_exec_mode before any mutation. Lane workers must explicitly load and use the installed `$sellable:create-campaign` wrapper as the nested workflow entrypoint, then load `create-campaign-v2` and `create-campaign-v2/core/flow.v2.json`; they must execute creation, source import, create-campaign workflow steps, generate-messages, sequence attachment, pause_campaign review-state transition when the current table is still DRAFT, and review readiness through that existing create-campaign workflow/subskills, then return receipts here for verification. Customer-visible verify receipts must set status:'succeeded' or status:'completed'; status:'passed', status:'pass', and status:'passed_with_warnings' are rejected as primary success statuses. Receipts must include createCampaignStepReceipt with setupPlanCall, createCampaignWorkflowReceipt, campaignBriefReceipt, sourceDecisionReceipt, filterDecisionReceipt, messageDraftingReceipt, reviewBatchReceipt, sequenceReceipt, and verifyCall nested inside createCampaignStepReceipt; top-level-only copies of those objects are not enough and are not promoted by verify. setupPlanCall must use canonical keys: planRevision, actionId, laneKey, workspaceId, senderIds, campaignId, tableId, createIntent. Do not use laneActionId, lanePacketActionId, delegatedPlanRevision, delegatedActionId, or requestedCall text as a substitute for those canonical fields. createCampaignWorkflowReceipt must include skillCommand:'$sellable:create-campaign', skillName:'create-campaign', wrapperSkillLoaded:true, workflowPromptName:'create-campaign-v2', workflowPromptLoadedToHasMoreFalse:true, workflowAssetPath:'create-campaign-v2/core/flow.v2.json', workflowAssetLoaded:true, workerRuntime, workerThreadId or receiptArtifactPath, durableReceiptWritten when using a receipt file, and notAdHoc:true. messageDraftingReceipt must use exactly statusSource:'branch' or statusSource:'packaged-generate-messages-worker'; descriptive aliases such as statusSource:'package-readback-local-thread' are rejected. It must include proof that generate-messages was loaded, start_campaign_message_preparation/get_campaign_message_preparation_status ran when the packaged worker path is used, validationResult:'passed', a passed qualityReview, and at least 3 concrete sampleMessages with rowId, generatedMessageText, verdict, and issues; Do not substitute `message` for `generatedMessageText`; Do not substitute `passVerdict` for `verdict`. Before writing durable receipts, run a receipt self-check: top-level `planRevision`, `actionId`, `laneKey`, `laneType`, `workspaceId`, and `senderIds` must exist; if the self-check fails, fix the receipt before ending. Use start_campaign_message_preparation with approvalMode:\"mark_ready\" only for evergreen setup. Never call `start_campaign_message_preparation` with `approvalMode:\"approve\"`; approve exactly one semantic Approved cell through select_campaign_cells/update_cell and final proof must show approvedGeneratedMessageCount exactly 1. Shared Cold Fallback samples with a standalone name followed by 'Hey there' are rejected. This command does not launch campaigns, does not schedule sends, does not assign scheduler-owned send fields, does not raw-write campaign status, does not archive/delete cleanup targets, and does not spend paid credits.",
         inputSchema: {
             type: "object",
             properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sellable/mcp",
-  "version": "0.1.419",
+  "version": "0.1.421",
   "type": "module",
   "description": "Sellable MCP server for Claude Code and Codex campaign workflows",
   "main": "dist/index.js",

package/skills/create-evergreen-campaigns/SKILL.md

@@ -14,6 +14,29 @@ producing duplicates. This skill never launches campaigns; customer-visible
 completion stops at paused send review.
 </role>
 
+## Invocation Mode Gate
+
+Before any setup plan, classify the invocation mode.
+
+- **Interactive approval mode is the default.** A bare user invocation such as
+  `$sellable:create-evergreen-campaigns`, "create evergreen campaigns", or
+  "set up evergreen" is interactive unless the prompt explicitly says `--yolo`,
+  scheduled, cron, automation, fresh-thread, run without approval, no user input,
+  or the host injects an equivalent trusted automation marker.
+- In interactive approval mode, first call
+  `setup_evergreen_campaigns({ mode:"plan", depth:"customer_visible", ... })`
+  **without** `yolo:true`, render the returned `approvalSummary`, and wait for
+  explicit operator approval before dispatching any lane worker or creating
+  product state.
+- In automation or explicit `--yolo` mode, pass `yolo:true` in plan mode only
+  and proceed without intermediate approval only when the plan returns
+  `autoExecutable:true`.
+
+Short form: no explicit automation/`--yolo` marker means plan-and-ask, not run.
+Short form: never infer `yolo:true` from a bare command invocation.
+Short form: command hosts that want Custer-style unattended execution must
+inject explicit automation context before invoking this skill.
+
 ## Operational Fast Path
 
 In automation or `--yolo` customer-visible setup, use this path before the
@@ -51,6 +74,21 @@ directory setup or product mutation.
 <inputs>
 The invoking prompt names the senders ("create evergreen campaigns for csreyes92 and thomas"). Resolve each via `list_senders`.
 
+If the invoking prompt is a normal user chat without an explicit automation or
+`--yolo` marker, run **interactive approval mode**:
+
+- Call `setup_evergreen_campaigns({ mode:"plan", depth:"customer_visible", ... })`
+  without `yolo:true`.
+- Render `approvalSummary.approvalQuestion` and the approval buckets
+  (`campaignsToCreate`, `campaignsToUpdate`, `campaignsToVerifyOnly`,
+  `campaignsLeftUntouched`, sender scopes, selected action ids, allowed and
+  forbidden side effects, blockers, and stop conditions).
+- Wait for an explicit approval that names or clearly accepts the rendered plan
+  before dispatching lane workers or mutating product state.
+- After approval, execute only the current `planRevision` and
+  `selectedActionIds`; re-plan if the planRevision, action ids, sender scopes,
+  blockers, side-effect classes, or lane bindings drift.
+
 If the invoking prompt says scheduled, automation, cron, heartbeat, fresh-thread,
 run without user input, or similar, run in **automation mode**:
 
@@ -269,11 +307,23 @@ sender scopes, explicit bindings, or an interactive session.
 
 When safe-yolo is blocked only because the plan needs normal setup work, ask
 for a **bounded delegated approval** over the rendered current plan instead of
-asking for each substep. The approval packet must name the workspace id, sender
-ids, lane keys, campaign/table ids or create intents, source/import caps,
-generate-message caps, route-proof approval policy, selectedActionIds,
-planRevision, allowed side-effect classes, and stop conditions. After that one
-approval covers the current planRevision, the parent may act on behalf of the
+asking for each substep. The approval request must be rendered from the plan's
+`approvalSummary`, not handwritten from raw lane packets alone. Show:
+
+- `workspaceId`, `planRevision`, and `selectedActionIds`.
+- Sender scopes with display names and ids: Post Engagers senders and shared-lane senders.
+- `campaignsToCreate`: each campaign/lane name, action id, create intent, attached senders, and allowed side effects.
+- `campaignsToUpdate`: each existing campaign/table id, current status/step, attached senders, and exact repairs or setup side effects.
+- `campaignsToVerifyOnly`: existing campaigns that will only be verified/read.
+- `campaignsLeftUntouched`: existing campaigns attached to selected senders but excluded from the current selected lane scope, with the reason.
+- Source/import caps, generate-message caps, route-proof approval policy, allowed side-effect classes, forbidden side effects, blockers, and stop conditions.
+
+If `approvalSummary.approvalQuestion` is present, use it as the short approval
+question and put the detailed buckets underneath. Do not ask a vague yes/no
+question that only says "run evergreen setup" or "approve this plan" without
+naming the campaigns to create, existing campaigns to update/verify, campaigns
+left untouched, and attached senders. After that one approval covers the current
+planRevision and selectedActionIds, the parent may act on behalf of the
 operator and execute the selectedActionIds end to end. Do not ask again for
 substep approvals for source import, create-campaign choices, Message Drafting,
 sequence attach/precheck, or exactly one route-proof approval when those actions
@@ -283,6 +333,7 @@ workspace id, sender ids, source/list id, campaign/table id, new campaign/table
 id, planRevision, actionId, selectedActionIds, allowed side effects, caps,
 status, or blocker set outside the approved packet.
 The short rule: one approval covers the current planRevision and selectedActionIds.
+The approval clarity rule: the operator approves named campaign create/update/verify/untouched buckets and attached senders, not a generic evergreen run.
 The execution rule: act on behalf of the operator; do not ask again for substep approvals while work stays within the lane packet, approved caps, approved side-effect classes, and route-proof approval policy.
 The drift rule: stop and re-plan when ids, caps, blockers, side-effect classes, or any new campaign/table id leave the approved packet.
 
@@ -448,10 +499,22 @@ Do not paste the entire wrapper skill into worker prompts. If the parent cannot
 launch at least one visible/durable worker immediately after directory setup,
 stop with `blocked: worker_dispatch_stalled` before any mutation.
 After launching workers, poll only the expected current-run receipt paths from
-`workerDispatch.receiptArtifactHint`. If no worker receipt file appears within a
-bounded wait, for example 10 minutes in automation, stop with
-`blocked: worker_receipt_timeout`, include the worker ids/final-file paths/stderr
-if available, and do not create or repair campaign shells in the parent.
+`workerDispatch.receiptArtifactHint`. Polling is progress-aware, not a blind
+wall-clock cutoff: while a visible/durable worker is still active and recent
+readbacks show forward progress, keep polling the expected path and do not
+report `worker_receipt_timeout`. If a worker is active but the receipt is still
+missing after the product postconditions appear complete, send exactly one
+receipt-write recovery prompt that says the worker must write either a success
+receipt or a blocked receipt at the exact path before ending. If no worker
+receipt file appears after a bounded **no-progress** window, for example 10
+minutes without new tool calls, final-file updates, receipt mtime changes, or
+thread progress, stop with `blocked: worker_receipt_timeout`, include the worker
+ids/final-file paths/stderr if available, and do not create or repair campaign
+shells in the parent.
+If a worker produced partial product state but no receipt, recover through the
+same visible/durable worker or a compact repair worker against the existing
+campaign/table ids; never create a duplicate lane campaign to recover a missing
+receipt.
 Use only the repo-local `workerDispatch.receiptArtifactHint` returned by the
 current lane packet for receipt paths.
 Do not hardcode machine-specific paths, workspace ids, campaign ids, sender ids, or UAT/phase artifact paths in this MCP prompt or any worker prompt.
@@ -477,6 +540,10 @@ Lane key: <laneKey>
 Allowed side effects: <allowedSideEffects JSON>
 Write the durable receipt to this exact path: <receiptArtifactPath>
 
+If your runtime exposes a goal tool, create or maintain this exact goal:
+complete action <actionId> only when <receiptArtifactPath> exists as valid JSON
+for this lane or when a blocked receipt has been written at that same path.
+
 Worker lane packet JSON:
 <lane packet JSON>
 
@@ -485,7 +552,14 @@ Use mcp__sellable only. Do not use admin tools, direct DB, Prisma, SQL, web sear
 Do not launch, start, schedule, send, or use paid InMail.
 For filter proof, durable receipt status must be `filterDecisionReceipt.status:"applied"` only; never `completed`, `confirmed`, `done`, or aliases.
 For generated messages, `update_cell` is allowed only for the semantic Approved checkbox. Never use `update_cell` for generated message text/body/sample copy. Bad copy requires `revise_message_template_and_rerun` or brief/template revision plus Generate Message rerun. Any generated-message cell override is `blocked: generated_message_cell_override`.
-Complete only this lane, write the required durable receipt JSON, and stop.
+Complete only this lane. Do not end with narration only. Before your final
+response, run a local file-existence and JSON self-check for
+<receiptArtifactPath>. If the lane succeeded, write the canonical success
+receipt there; if any postcondition, quality gate, verifier schema, or file
+write blocks, write a canonical blocked receipt there with `status:"blocked"`,
+`blocker`, `campaignId`, `tableId`, `actionId`, `laneKey`, `planRevision`, and
+the latest product readback. The terminal condition is filesystem proof that
+<receiptArtifactPath> exists.
 WORKER_PROMPT
 
 # Multi-worker launcher equivalent:
@@ -1015,6 +1089,13 @@ every canonical verifier object under `createCampaignStepReceipt`, including
 `campaignBriefReceipt`, `sourceDecisionReceipt`, `filterDecisionReceipt`,
 `messageDraftingReceipt`, `reviewBatchReceipt`, `sequenceReceipt`,
 `finalPausedSendProof`, and `verifyCall`.
+Write the compact verifier payload to a temporary JSON file and load that object
+directly into the MCP verify call. Do not manually paste, retype, truncate, or
+merge full receipt JSON into the tool call. If a verify attempt fails because
+the payload was malformed, overlong, manually edited, missing a receipt, or used
+a later reuse planRevision/actionId set, rebuild the compact payload from the
+durable receipt files and retry once with the original execution
+`planRevision`/`selectedActionIds` before reporting a verifier blocker.
 When compacting, normalize `finalPausedSendProof.currentStep` and
 `finalPausedSendProof.campaignStatus` from nested pause/navigation readbacks if
 the worker receipt stored those values under `pauseCampaignResult`,
@@ -1029,6 +1110,7 @@ Short form: Do not use complex inline `jq` for receipt compaction; use Node.
 Short form: Compact receipts must preserve `researchSenderReceipt`.
 Short form: Compact receipts must preserve direct `finalPausedSendProof.currentStep` and `campaignStatus`.
 Short form: Never change planRevision/actionId/laneKey while compacting receipts.
+Short form: Do not hand-build giant receipt tool-call payloads; load compact JSON from disk.
 
 Parent repair dispatch uses the same compact discipline. If the parent sample
 quality gate fails after a worker receipt, do not launch a repair worker by