@sellable/mcp 0.1.552 → 0.1.553

package/skills/refill-sends/SKILL.md

@@ -83,6 +83,8 @@ Accepted invocation flags in the same user request:
 - `senderIds: <id>, <id>` or `senderNames: <name>, <name>`: explicit selector
   alternatives when the host preserves natural-language arguments better than
   shell-style flags.
+- `actionTypes: send_invite, send_inmail_closed`: optional lane selector. Omit
+  `actionTypes` to preserve the target planner's lane inference.
 - `untilDate: YYYY-MM-DD`: explicit date selector alternative when the host
   preserves natural-language arguments better than shell-style flags.
 - `targetDate: YYYY-MM-DD`: exact-date selector alternative when the host
@@ -91,7 +93,7 @@ Accepted invocation flags in the same user request:
 When the host can call typed MCP tools, start with:
 
 ```text
-refill_sends({ yolo?: boolean, executionMode?: "manual" | "scheduled" | "yolo", requireWorkspace?: boolean, workspaceId?: string, senders?: string[], senderIds?: string[], senderNames?: string[], horizonSendDays?: number, untilDate?: "YYYY-MM-DD", targetDate?: "YYYY-MM-DD" })
+refill_sends({ yolo?: boolean, executionMode?: "manual" | "scheduled" | "yolo", requireWorkspace?: boolean, workspaceId?: string, senders?: string[], senderIds?: string[], senderNames?: string[], actionTypes?: ("send_invite" | "send_inmail_closed")[], horizonSendDays?: number, untilDate?: "YYYY-MM-DD", targetDate?: "YYYY-MM-DD" })
 ```
 
 That command helper normalizes arguments and returns the execution contract. In
@@ -99,14 +101,22 @@ non-yolo mode it does not mutate. In `--yolo`, it may execute exactly one safe
 bounded primitive from the fresh `target.globalActionQueue[0]`, then reread and
 return the new target plan; currently safe primitives are paid-credit refresh,
 existing-row message preparation, generated-message approval, receipt-proven
-same-source row copy, and read-only wait rereads. Same-source copy/source
+same-source row copy, a request-scoped exact-date product scheduler sweep, and
+read-only wait rereads. Same-source copy/source
 fallback is safe only after receipt-proven exhaustion:
 `hasMoreFrontierRows:false`, zero `approvalCandidates`, no `stuckActiveCells`,
-and no non-terminal `approvedNotDispatched` work. It does not run unbounded approval, lower
-paid-InMail thresholds, switch source families, create campaigns, launch, send,
-or write scheduler rows. Continue with the workflow below for route selection,
-state rereads, approval gating, source import, preparation, and bounded
-approval.
+and no non-terminal `approvedNotDispatched` work. It does not run unbounded
+approval, lower paid-InMail thresholds, switch source families, create
+campaigns, launch, or send directly; it never raw-writes scheduler fields.
+Continue with the workflow below for route selection, state rereads, approval
+gating, source import, preparation, and bounded approval.
+
+The approval scope is the exact `workspaceId`, `targetDate`, sender ids, action
+types, campaign/table/source ids, `targetShapeRevision`, and `actionKey` in the
+rendered packet. `stateRevision` and sent/scheduled/ready counts are mutable
+progress, not approval-scope drift. Execute only
+`target.globalActionQueue[0]`, then perform a full authoritative reread before
+deciding any next action.
 
 ## Workspace Contract
 
@@ -284,6 +294,19 @@ When the refill loop has ready rows and needs scheduler pickup now, use
 `run_scheduler_sweep` with the same explicit `workspaceId`; it can place cells
 within existing scheduler gates and returns the receipt, but it never sends or
 bypasses limits.
+A scheduler sweep is a visible workspace-wide scheduling side effect. The
+request packet limits the expected target changes to its exact date, senders,
+action types, campaigns, tables, and stable sources, but the product scheduler
+may also place unrelated eligible workspace work; disclose that possibility in
+the approval packet and receipt. For an exact-date sweep action, execute it
+once, then reread the full target plan before taking or presenting another
+action.
+The exact-date `run_scheduler_sweep` may schedule eligible workspace cells
+through existing product gates; it never sends directly or raw-writes scheduler
+fields. Only non-exact or no-sweep scheduler waits are read-only.
+On resume, reconcile the current target plan and matching sweep status/receipt
+before retrying. A matching same-key terminal receipt replays; an
+`uncertain_outcome` stops for reconciliation and must not schedule again.
 Scheduler-run receipt interpretation: `cellsConsidered is allocation-attempt
 count`, not total ready supply, while `readyCellsFound` is ready inventory found
 before prefilters. Inspect `campaignScopeSummary` before assuming the selected
@@ -396,6 +419,14 @@ scheduler wait loop. Do not finish the refill goal, mark it complete, or mark it
 blocked only because it is still `awaiting_scheduler_after_ready_buffer`; keep
 waiting unless Christian stops the run or the host cannot continue.
 
+Future scheduled coverage and already sent actions are distinct; only
+scheduler-owned future scheduled actions count as scheduled coverage. For
+multiple target dates, finish D1 execution and the full D1 reread before
+planning D2. Completion proof is product-native Sellable MCP evidence only:
+target plan, campaign refill state, scheduler capacity, sweep/status, and
+bounded receipts. Never use individual cell ids, Prisma, SQL, direct database
+access, or production-environment scripts as completion proof.
+
 In `--yolo`, the default fill target is the scheduler-forward 48-hour window
 unless `--target-date`/`targetDate`, `--until`/`untilDate`, or an explicit
 compatibility `horizonSendDays` is provided. If a target date is provided,

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

@@ -75,6 +75,20 @@ calls, preparation calls, approval calls, and campaign start calls. Missing
 interactive workspace switching is diagnostic setup only and is not an
 automation control path.
 
+Typed command scope:
+
+```text
+refill_sends({ yolo?: boolean, executionMode?: "manual" | "scheduled" | "yolo", requireWorkspace?: boolean, workspaceId?: string, senders?: string[], senderIds?: string[], senderNames?: string[], actionTypes?: ("send_invite" | "send_inmail_closed")[], horizonSendDays?: number, untilDate?: "YYYY-MM-DD", targetDate?: "YYYY-MM-DD" })
+```
+
+Omit `actionTypes` to preserve the target planner's lane inference. The
+approval scope is the exact `workspaceId`, `targetDate`, sender ids, action
+types, campaign/table/source ids, `targetShapeRevision`, and `actionKey` in the
+rendered packet. `stateRevision` and sent/scheduled/ready counts are mutable
+progress, not approval-scope drift. Execute only
+`target.globalActionQueue[0]`, then perform a full authoritative reread before
+deciding any next action.
+
 Goal-mode continuation: a skill cannot create or invoke `/goal` by itself. When
 this workflow is already running inside an active Codex goal, keep that goal
 open until every selected sender lane is horizon-filled by projected coverage
@@ -192,6 +206,19 @@ files or memory.
    `run_scheduler_sweep` with the same explicit `workspaceId` to request the
    product scheduler placement pass now and read its receipt. This may place
    cells within existing gates, never sends messages, and never bypasses limits.
+   A scheduler sweep is a visible workspace-wide scheduling side effect. The
+   request packet limits expected target changes to the exact date, senders,
+   action types, campaigns, tables, and stable sources, but unrelated eligible
+   workspace work may also be scheduled by the product scheduler and must be
+   disclosed. For an exact-date sweep action, execute it once and perform the
+   full target-plan reread before taking or presenting another action.
+   The exact-date `run_scheduler_sweep` may schedule eligible workspace cells
+   through existing product gates; it never sends directly or raw-writes
+   scheduler fields. Only non-exact or no-sweep scheduler waits are read-only.
+   On resume, reconcile the current target plan and matching sweep
+   status/receipt before retrying. A matching same-key terminal receipt
+   replays; an `uncertain_outcome` stops for reconciliation and must not
+   schedule again.
    Scheduler-run receipt interpretation: `cellsConsidered is
    allocation-attempt count`, not total ready supply, while `readyCellsFound`
    is ready inventory found before prefilters. Inspect `campaignScopeSummary`
@@ -210,8 +237,10 @@ files or memory.
    scheduled count, projected count, campaign ids, and no-op proof without
    asking for approval or mutating.
    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
+   InMail credit freshness is clean for every selected paid-InMail lane,
+   execute an exact-date `run_scheduler_sweep` action once when it is
+   `target.globalActionQueue[0]`, then fully reread. Otherwise, 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
@@ -384,10 +413,11 @@ exceeds the sender's capacity for the selected target window. Put another way:
 complete when the same daily-limit/readback model would show no remaining
 send-day capacity for that selected lane. Ready-to-schedule rows are only buffer
 for the product scheduler. If ready plus projected coverage covers the target
-window but scheduled cells do not yet, run a persistent read-only scheduler wait
-loop: wait, reread, recompute the ledger, and continue until projected coverage
-is proved, a concrete non-scheduler blocker appears, or Christian explicitly
-stops or asks for status only. `awaiting_scheduler_after_ready_buffer` is not
+window but scheduled cells do not yet, execute the exact-date sweep when the
+planner emits it; otherwise run a persistent read-only scheduler wait loop:
+wait, reread, recompute the ledger, and continue until projected coverage is
+proved, a concrete non-scheduler blocker appears, or Christian explicitly stops
+or asks for status only. `awaiting_scheduler_after_ready_buffer` is not
 success and is not a terminal blocker for an active refill goal; it is the
 loaded, awaiting scheduler poll state that keeps the thread waiting. It does not
 need a prep/import/approval packet.
@@ -720,6 +750,14 @@ with non-null `scheduledFor`. Prepared, approved, and ready-to-schedule rows are
 intermediate states; report them as awaiting scheduler unless scheduled cells
 are present.
 
+Future scheduled coverage and already sent actions are distinct; only
+scheduler-owned future scheduled actions count as scheduled coverage. For
+multiple target dates, finish D1 execution and the full D1 reread before
+planning D2. Completion proof is product-native Sellable MCP evidence only:
+target plan, campaign refill state, scheduler capacity, sweep/status, and
+bounded receipts. Never use individual cell ids, Prisma, SQL, direct database
+access, or production-environment scripts as completion proof.
+
 preparedMessages can remain 0 while scheduler-ready state changes downstream.
 After a prep job reaches a terminal state, run `wait_for_campaign_processing`
 when generated/pass counts are still settling, then poll `get_campaign_refill_state` until `readyToSchedule` drops, scheduled counts increase, or the state clearly

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

@@ -61,6 +61,44 @@
     "scheduled",
     "projected"
   ],
+  "scopeContract": {
+    "immutableApprovalEnvelope": [
+      "workspaceId",
+      "targetDate",
+      "senderIds",
+      "actionTypes",
+      "campaignIds",
+      "tableIds",
+      "sourceIds",
+      "targetShapeRevision",
+      "actionKey"
+    ],
+    "mutableProgress": [
+      "stateRevision",
+      "sent",
+      "scheduled",
+      "readyToSchedule",
+      "remainingProjectedGap"
+    ],
+    "executionRules": [
+      "Execute only target.globalActionQueue[0].",
+      "Execute one action, then perform a full authoritative reread before selecting any next action.",
+      "Mutable progress must not be treated as approval-scope drift while targetShapeRevision remains stable."
+    ]
+  },
+  "interruptionRecovery": {
+    "rules": [
+      "On resume, reread the canonical target plan and reconcile scheduler status or receipt with the matching requestKey and actionKey before retrying.",
+      "A matching terminal receipt must replay without a second scheduler execution.",
+      "An uncertain_outcome requires reconciliation; do not schedule again with the same or a replacement key until a canonical read resolves it."
+    ]
+  },
+  "multiDayOrdering": {
+    "rules": [
+      "For multiple target dates, finish D1 execution and the full D1 reread before planning D2.",
+      "Do not pre-plan or execute a later date from stale earlier-date state."
+    ]
+  },
   "states": [
     {
       "id": "target_plan_read",
@@ -188,7 +226,7 @@
     },
     {
       "id": "scheduler_wait_readback",
-      "description": "Read-only scheduler polling after rows are ready and paid-credit facts are fresh.",
+      "description": "Exact-date scheduler sweep or read-only polling after rows are ready and paid-credit facts are fresh.",
       "allowedTools": [
         "get_refill_target_plan",
         "get_scheduler_fill_capacity",
@@ -203,6 +241,9 @@
       "rules": [
         "Poll every 60-120 seconds or on the host continuation interval.",
         "Use run_scheduler_sweep with the explicit workspaceId when ready rows need scheduler pickup now; it places cells only inside existing gates and never sends.",
+        "A scheduler sweep is a visible workspace-wide scheduling side effect; the packet limits expected target changes but must disclose that unrelated eligible workspace work may also be scheduled.",
+        "For an explicit targetDate, execute only the request-scoped run_scheduler_sweep from target.globalActionQueue[0], then perform a full authoritative target-plan reread before any next action.",
+        "Reuse the matching requestKey and actionKey only for status or receipt reconciliation; replay a matching terminal receipt and stop on uncertain_outcome rather than scheduling again.",
         "cellsConsidered is allocation-attempt count; inspect campaignScopeSummary before assuming the selected refill campaign/table was included or ready-but-blocked.",
         "Read prefiltered, skipped, and deferred separately: prefiltered ready closed-InMail cells with stale paid-credit facts require refresh_paid_inmail_credits_then_rerun once, then rerun/status.",
         "wait_for_capacity_or_window means report loaded/capped/waiting and do not source or prep more rows; no_ready_cells_continue_refill_prep means return to the refill/prep ladder.",
@@ -211,6 +252,11 @@
         "Do not mark complete or blocked only because awaiting_scheduler_after_ready_buffer persists."
       ],
       "transitions": [
+        {
+          "when": "explicit targetDate and target.globalActionQueue[0] is request-scoped run_scheduler_sweep",
+          "action": "execute exactly one request-scoped run_scheduler_sweep, capture its complete receipt, and do not execute a returned next action",
+          "to": "target_plan_read"
+        },
         {
           "when": "projected coverage fills target",
           "to": "completion_or_blocker"
@@ -243,6 +289,7 @@
       "start_campaign_message_preparation",
       "same_source_copy",
       "bounded_generated_message_approval",
+      "run_scheduler_sweep",
       "wait_for_scheduler"
     ],
     "neverAutoExecute": [
@@ -271,11 +318,26 @@
   "verification": {
     "requiredProof": [
       "final get_refill_target_plan",
+      "get_campaign_refill_state for selected campaign/table facts",
+      "get_scheduler_fill_capacity for the exact sender/action/date",
+      "run_scheduler_sweep status or receipt for any executed sweep",
       "projected coverage sent + scheduled",
       "scheduler-owned cells with non-null scheduledFor when claiming scheduled",
       "paid-InMail freshness status clean before scheduler wait",
       "refresh receipt for each refreshed sender"
     ],
+    "forbiddenProof": [
+      "individual cell ids",
+      "Prisma",
+      "SQL",
+      "direct database access",
+      "production-environment scripts"
+    ],
+    "completionRules": [
+      "Report already sent actions separately from future scheduled actions.",
+      "Only scheduler-owned future scheduled actions count as scheduled coverage.",
+      "Prepared, approved, and ready rows remain intermediate evidence."
+    ],
     "notCompletionProof": [
       "prepared rows alone",
       "approved rows alone",