@sellable/mcp 0.1.510 → 0.1.512

package/skills/refill-sends-evergreen/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: refill-sends-evergreen
+description: Plan evergreen waterfall send refill work through the Phase 85 dry-run workflow.
+visibility: public
+allowed-tools:
+  - mcp__sellable__refill_sends_evergreen
+  - mcp__sellable__get_evergreen_refill_plan
+  - mcp__sellable__get_subskill_prompt
+  - mcp__sellable__get_subskill_asset
+  - mcp__sellable__get_auth_status
+  - mcp__sellable__get_active_workspace
+  - mcp__sellable__list_workspaces
+  - mcp__sellable__get_workspace
+---
+
+# Refill Sends Evergreen
+
+Use this public command wrapper for evergreen waterfall refill requests such as
+"refill evergreen", "fill evergreen senders", "load evergreen lanes", or
+"plan evergreen refill".
+
+Host command names:
+
+- Claude Code: `/sellable:refill-sends-evergreen`
+- Codex: `$sellable:refill-sends-evergreen`
+
+Phase 85 is read-only, dry-run, zero mutations. It plans the deterministic
+waterfall-ladder refill packet and writes a local dry-run journal, but it does
+not prepare messages, approve messages, start campaigns, schedule sends, send
+messages, refresh paid InMail credit facts, create campaigns, or change source
+configuration. Execution ships in the follow-up phase.
+
+## Entry
+
+Resolve the explicit `workspaceId` from the request, automation config, or
+active workspace readback. Scheduled or autonomous usage must carry
+`workspaceId` on every tool call. If the workspace is missing or ambiguous, stop
+with `WORKSPACE_REQUIRED`; do not switch the shared active workspace.
+
+Start with the command contract:
+
+```text
+refill_sends_evergreen({ workspaceId })
+```
+
+Then load the internal workflow prompt and flow asset:
+
+```text
+get_subskill_prompt({ subskillName: "refill-sends-evergreen-workflow" })
+get_subskill_asset({ subskillName: "refill-sends-evergreen-workflow", assetPath: "core/flow.v1.json" })
+```
+
+Continue both loads until `hasMore:false`; parse the flow JSON and verify
+`workflow:"refill-sends-evergreen-workflow"` with a `v1` version before the
+planner call.
+
+Call the dry-run planner with the explicit workspace id:
+
+```text
+get_evergreen_refill_plan({ workspaceId, senderIds?, runState?, journal?, journalNote? })
+```
+
+Use `senderIds` only when the user scoped the request to exact senders. Use
+`runState` only for an explicit what-if dry run; otherwise let the MCP read
+local lane memory hints. Leave `journal` enabled unless the user specifically
+asked for no local journal.
+
+## Report
+
+Review the returned packet before giving a recommendation:
+
+- `planRevision` starts with `pr1:`.
+- `stateRevision` identifies the current readback.
+- `packet` is the operator-facing facts receipt.
+- `plans[]` contains per-sender lane decisions and itinerary details.
+- `globalActionQueue[]` is a dry-run sequence only in Phase 85.
+- `evergreen.enumeratedRungs` and each action's `evergreenRung` map to the
+  locked ladder from the workflow asset.
+- `journalPath` points to the dry-run markdown journal written by the MCP.
+- `sideEffects` must be all false.
+
+Report campaign names and sender names first, ids second. Include the chosen
+rung, the itinerary, the plan revision, the journal path, and any blockers or
+warnings. Stop after the report; do not execute the action queue in Phase 85.

package/skills/refill-sends-evergreen-workflow/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: refill-sends-evergreen-workflow
+description: Internal read-only workflow for evergreen waterfall refill dry-run planning.
+visibility: internal
+allowed-tools:
+  - mcp__sellable__refill_sends_evergreen
+  - mcp__sellable__get_evergreen_refill_plan
+  - mcp__sellable__get_subskill_prompt
+  - mcp__sellable__get_subskill_asset
+  - mcp__sellable__get_auth_status
+  - mcp__sellable__get_active_workspace
+  - mcp__sellable__list_workspaces
+  - mcp__sellable__get_workspace
+---
+
+# Refill Sends Evergreen Workflow
+
+This internal workflow is the Phase 85 plan surface for evergreen waterfall
+refill. It is read-only, dry-run, zero mutations. The workflow has three gates:
+bootstrap, plan, and report.
+
+Runtime flow asset: after loading this prompt, load
+`get_subskill_asset({ subskillName: "refill-sends-evergreen-workflow", assetPath: "core/flow.v1.json" })`
+through MCP, continue chunks until `hasMore:false`, parse the JSON, and verify
+`workflow:"refill-sends-evergreen-workflow"` with a `v1` version before any
+planner call. If the asset cannot load or parse, stop with
+`blocked:evergreen_refill_workflow_asset_unavailable`; do not emulate it from
+local files or memory.
+
+## G0 Bootstrap Facts
+
+Resolve the request-scoped `workspaceId` using read-only auth and workspace
+tools. Scheduled or autonomous runs must not rely on implicit workspace state.
+Call `refill_sends_evergreen({ workspaceId })` first to receive the command
+contract, then call `get_evergreen_refill_plan({ workspaceId })` for the dry-run
+packet.
+
+Optional inputs:
+
+- `senderIds`: exact sender scope when the user named senders.
+- `runState`: synthetic v1 lane memory for what-if dry runs. Use it only when
+  the user intentionally wants a hypothetical cursor, pin, or cooldown state.
+- `journal:false`: skip the local journal only when explicitly requested.
+- `journalNote`: append operator context to the dry-run terminal section.
+
+## G1 Evergreen Ladder
+
+The planner chooses from this locked rung order:
+
+1. `start_campaign`: a paused selected lane has scheduler-ready supply but must
+   be live before the scheduler can pick it up.
+2. `approve_messages`: generated rows are ready for a bounded approval step.
+3. `wait_for_active_work`: enrichment, generation, import, or preparation is
+   already active, so the next honest action is to wait for that work to finish.
+4. `enrich_more`: exact-set enrichment can close the current ready gap.
+5. `reconcile_source_copy`: same-source rows exist and can be copied without
+   changing source family or source fingerprint.
+6. `add_leads_same_source`: the same source path can add bounded new supply.
+7. `paid_lane_fallback`: paid InMail is blocked or below threshold, so the same
+   waterfall can fall back to an existing supported lane.
+8. `next_campaign`: the current lane is exhausted, cooling down, pinned away, or
+   unsafe, and the next surviving campaign lane should be inspected.
+9. `wait_for_scheduler`: ready or projected supply covers the target, and only
+   scheduler pickup remains.
+10. `done`: the sender or lane is complete for the selected target window, or a
+    scheduler cap makes additional preparation unnecessary.
+
+Forward-only lane rule: a lane can move to a later rung or a later surviving
+campaign, but the dry-run packet must not jump backward to invent work that the
+facts do not support. Pinned-campaign rule: a pinned campaign stays selected
+until the planner proves a blocker, cooldown, exhaustion, or safer next lane.
+Capped-is-complete rule: when scheduler capacity is lower than the requested
+target and ready/projected coverage satisfies that cap, report `done` with the
+cap reason. Honest-itinerary rule: show what was checked, what was skipped, and
+why; never hide uncertainty behind a confident source recommendation.
+
+Guardrails inherited from the Phase 83 evergreen workflow: no campaign creation,
+no provider-family switch, no threshold lowering, no scheduler writes, no
+launch/send/archive/delete, no brief/filter/message/sequence/sender mutation,
+no message preparation, no message approval, no paid InMail credit refresh, no
+source mutation, no row queueing, and no campaign status change.
+
+## Journal
+
+`get_evergreen_refill_plan` writes a local dry-run journal unless
+`journal:false` is passed. Read the returned `journalPath` from the tool result
+and include it in the report. The journal contains bootstrap, plan, and terminal
+sections plus an index line under the run journal directory. If the tool returns
+`journalPath:null` with a `journalWriteFailed` warning, report the warning and
+continue with the dry-run packet; do not retry by writing local files yourself.
+
+## Report Contract
+
+Completion for Phase 85 means packet reviewed and journal written. Merely
+calling `get_evergreen_refill_plan` is not completion proof.
+
+Report these facts:
+
+- workspace id and selected sender scope;
+- plan revision and state revision;
+- selected campaign and lane per sender;
+- chosen rung and dry-run action queue;
+- itinerary, skipped lanes, blockers, cooldowns, and warnings;
+- journal path;
+- side effects proof, which must show all false values.
+
+Stop after the report. The Phase 85 workflow never executes the action queue.

package/skills/refill-sends-evergreen-workflow/core/flow.v1.json

@@ -0,0 +1,247 @@
+{
+  "version": "v1.0",
+  "workflow": "refill-sends-evergreen-workflow",
+  "principle": "Plan evergreen waterfall refill as a read-only dry-run with zero mutations.",
+  "enumeratedRungs": [
+    "start_campaign",
+    "approve_messages",
+    "wait_for_active_work",
+    "enrich_more",
+    "reconcile_source_copy",
+    "add_leads_same_source",
+    "paid_lane_fallback",
+    "next_campaign",
+    "wait_for_scheduler",
+    "done"
+  ],
+  "requiredBootstrap": [
+    {
+      "tool": "get_auth_status",
+      "purpose": "Confirm MCP auth before reading workspace or plan facts."
+    },
+    {
+      "tool": "get_active_workspace",
+      "purpose": "Resolve explicit workspace evidence when the request did not provide workspaceId."
+    },
+    {
+      "tool": "refill_sends_evergreen",
+      "requiredValues": {
+        "workspaceId": "{workspaceId}"
+      },
+      "requiredOutput": [
+        "readOnly true",
+        "approvalContract says Phase 85 is plan-only"
+      ]
+    },
+    {
+      "tool": "get_subskill_prompt",
+      "requiredValues": {
+        "subskillName": "refill-sends-evergreen-workflow"
+      },
+      "mustReadUntil": {
+        "hasMore": false
+      }
+    },
+    {
+      "tool": "get_subskill_asset",
+      "requiredValues": {
+        "subskillName": "refill-sends-evergreen-workflow",
+        "assetPath": "core/flow.v1.json"
+      },
+      "mustReadUntil": {
+        "hasMore": false
+      },
+      "validation": {
+        "workflow": "refill-sends-evergreen-workflow",
+        "versionPrefix": "v1",
+        "requiredTopLevelKeys": [
+          "states",
+          "gateOrder",
+          "enumeratedRungs",
+          "verification"
+        ]
+      }
+    },
+    {
+      "tool": "get_evergreen_refill_plan",
+      "requiredValues": {
+        "workspaceId": "{workspaceId}"
+      },
+      "requiredOutput": [
+        "planRevision",
+        "stateRevision",
+        "packet",
+        "journalPath",
+        "sideEffects"
+      ]
+    }
+  ],
+  "gateOrder": ["bootstrap", "plan", "report"],
+  "states": [
+    {
+      "id": "bootstrap",
+      "description": "Load the read-only command contract, workflow prompt, flow asset, and workspace facts.",
+      "allowedTools": [
+        "get_auth_status",
+        "get_active_workspace",
+        "list_workspaces",
+        "get_workspace",
+        "refill_sends_evergreen",
+        "get_subskill_prompt",
+        "get_subskill_asset",
+        "get_evergreen_refill_plan"
+      ],
+      "onEnter": [
+        {
+          "tool": "get_auth_status"
+        },
+        {
+          "tool": "refill_sends_evergreen",
+          "requiredFields": ["workspaceId"]
+        },
+        {
+          "tool": "get_subskill_prompt",
+          "requiredValues": {
+            "subskillName": "refill-sends-evergreen-workflow"
+          }
+        },
+        {
+          "tool": "get_subskill_asset",
+          "requiredValues": {
+            "subskillName": "refill-sends-evergreen-workflow",
+            "assetPath": "core/flow.v1.json"
+          }
+        }
+      ],
+      "transitions": {
+        "contract_loaded": "plan"
+      }
+    },
+    {
+      "id": "plan",
+      "description": "Call the dry-run evergreen refill planner exactly once for this invocation.",
+      "allowedTools": ["get_evergreen_refill_plan"],
+      "onEnter": [
+        {
+          "tool": "get_evergreen_refill_plan",
+          "requiredFields": ["workspaceId"],
+          "optionalFields": ["senderIds", "runState", "journal", "journalNote"]
+        }
+      ],
+      "requiredOutput": [
+        "sideEffects all false",
+        "planRevision starts with pr1:",
+        "journalPath reported",
+        "chosen evergreenRung is in enumeratedRungs"
+      ],
+      "allowedRungsSource": "enumeratedRungs",
+      "doNotAllow": [
+        "add_column",
+        "add_on_demand_leads",
+        "add_rubric_item",
+        "add_teammate",
+        "add_to_comment_campaign",
+        "add_to_connection_campaign",
+        "add_to_inmail_campaign",
+        "archive_campaign",
+        "attach_recommended_sequence",
+        "attach_sequence",
+        "bulk_enrich_with_prospeo",
+        "cancel_campaign_message_preparation",
+        "cancel_lead_import",
+        "capture_post_idea",
+        "check_rubric",
+        "commit_blueprint",
+        "confirm_harvest_job_companies",
+        "confirm_lead_list",
+        "confirm_prospeo_company_accounts",
+        "copy_sender_config",
+        "create_campaign",
+        "create_on_demand_campaign",
+        "create_on_demand_table",
+        "create_workspace",
+        "create_workflow_table",
+        "delete_column",
+        "delete_rubric_item",
+        "duplicate_campaign",
+        "enrich_with_prospeo",
+        "fill_campaign_horizon",
+        "get_or_create_direct_campaign_table",
+        "import_leads",
+        "load_csv_dnc_entries",
+        "load_csv_domains",
+        "load_csv_linkedin_leads",
+        "mark_post_published",
+        "migrate_flat_configs",
+        "pause_campaign",
+        "pause_direct_campaign",
+        "pause_on_demand_campaign",
+        "prepare_campaign_ab_test",
+        "queue_campaign_cells",
+        "queue_cells",
+        "record_campaign_review_batch",
+        "record_engage_proven_search",
+        "refill_sends",
+        "refresh_paid_inmail_credits",
+        "revise_message_template_and_rerun",
+        "save_domain_filters",
+        "save_hook_research",
+        "save_post_draft",
+        "save_rubrics",
+        "send_inbox_draft",
+        "send_inbox_manual_reply",
+        "set_active_workspace",
+        "set_campaign_waterfall_order",
+        "set_company_info",
+        "set_engage_state",
+        "set_engage_style_guide",
+        "set_headline_icp_criteria",
+        "set_sender_routing",
+        "setup_evergreen_campaigns",
+        "start_campaign",
+        "start_campaign_message_preparation",
+        "start_direct_campaign",
+        "start_on_demand_campaign",
+        "update_campaign",
+        "update_campaign_brief",
+        "update_cell",
+        "update_column",
+        "update_inbox_draft",
+        "update_post_draft",
+        "update_published_post_metrics",
+        "update_rubric_item",
+        "upsert_engage_tracked_person",
+        "upsert_rubric"
+      ],
+      "transitions": {
+        "packet_returned": "report"
+      }
+    },
+    {
+      "id": "report",
+      "description": "Present packet, itinerary, warnings, blockers, plan revision, and journal path; then stop.",
+      "allowedTools": [],
+      "onEnter": [
+        {
+          "action": "present_packet_itinerary_and_journal_path"
+        }
+      ],
+      "terminal": true
+    }
+  ],
+  "verification": {
+    "requiredProof": [
+      "sideEffects all false in get_evergreen_refill_plan response",
+      "planRevision has pr1: prefix",
+      "journalPath reported or journalWriteFailed warning surfaced",
+      "chosen evergreenRung belongs to enumeratedRungs",
+      "packet reviewed with itinerary and blockers"
+    ],
+    "notCompletionProof": [
+      "called get_evergreen_refill_plan alone",
+      "action queue exists",
+      "ready rows alone",
+      "operator wants execution"
+    ]
+  }
+}

package/skills/refill-sends-workflow/SKILL.md

@@ -3,6 +3,7 @@ name: refill-sends-workflow
 description: Internal skill-led refill sends workflow for regular campaigns and evergreen campaigns.
 visibility: internal
 allowed-tools:
+  - mcp__sellable__get_subskill_asset
   - mcp__sellable__get_refill_target_plan
   - mcp__sellable__get_scheduler_fill_capacity
   - mcp__sellable__refresh_paid_inmail_credits
@@ -79,6 +80,16 @@ open until every selected sender lane is horizon-filled by projected coverage
 non-scheduler blocker appears. `awaiting_scheduler_after_ready_buffer` is an
 in-progress wait state, not a reason to mark the goal complete or blocked.
 
+Runtime flow asset: after loading this prompt, load
+`get_subskill_asset({ subskillName: "refill-sends-workflow", assetPath: "core/flow.v1.json" })`
+through MCP, continue chunks until `hasMore:false`, parse the JSON, and verify
+`workflow:"refill-sends-workflow"` with a `v1` version before any operational
+step. The flow asset is the deterministic gate order: target-plan read, paid
+InMail credit freshness gate, action selection, bounded table action, scheduler
+wait readback, then completion/blocker. If the asset cannot load or parse, stop
+with `blocked:refill_workflow_asset_unavailable`; do not emulate it from local
+files or memory.
+
 1. Call `get_refill_target_plan` first. This read-only target plan is the
    canonical opening receipt: eligible senders, selected sender-local days,
    gross target, inferred per-sender send lane/action selections, actual sent
@@ -136,6 +147,19 @@ in-progress wait state, not a reason to mark the goal complete or blocked.
    threshold, below-threshold paid-InMail facts fall back to an existing
    connection lane, the same Sales Nav cascade campaign's connection branch, or
    a manual continuation.
+   Freshness gate precedes scheduler wait: if any selected
+   `target.senderRefillPlans[].paidInmail.status` is `missing_credit_facts` or
+   `stale_credit_facts`, or the target plan contains a
+   `refresh_paid_inmail_credits` candidate, do not enter
+   `wait_for_scheduler` even when `remainingReadyOrProjectedGap:0`. Refresh the
+   exact selected sender credit facts once, rerun `get_refill_target_plan`, and
+   only then decide whether scheduler wait is the next safe action. If facts
+   remain missing/stale after the single refresh attempt, stop with a
+   paid-InMail freshness blocker instead of waiting on scheduler pickup.
+   The standalone MCP refresh surface is the scoped route
+   `/api/v3/mcp/senders/:senderId/refresh-inmail-credits` with explicit
+   `workspaceId`; do not use active-workspace mutation as the automation
+   control path.
    Compact refill lessons: sender-level target plan is final truth; trust
    `schedulerGate.sendable` and scheduler gate blockers, not raw
    `unipileAccountStatus` labels alone; use compact prep status checks for
@@ -154,8 +178,9 @@ in-progress wait state, not a reason to mark the goal complete or blocked.
    If `status:"complete"`, report the target, selected dates, sent count,
    scheduled count, projected count, campaign ids, and no-op proof without
    asking for approval or mutating.
-   If `remainingReadyOrProjectedGap:0` but `remainingProjectedGap>0`, run only a
-   persistent read-only scheduler wait/reread loop; do not ask for
+   If `remainingReadyOrProjectedGap:0` but `remainingProjectedGap>0`, and paid
+   InMail credit freshness is clean for every selected paid-InMail lane, run
+   only a persistent read-only scheduler wait/reread loop; do not ask for
    prep/import/approval. Poll `get_refill_target_plan` every 60-120 seconds, or
    on the host's next continuation interval, until projected coverage fills,
    a concrete non-scheduler blocker appears, or Christian explicitly asks to