@sellable/mcp 0.1.557 → 0.1.558

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

@@ -30,6 +30,22 @@
           "yoloMode"
         ]
       }
+    },
+    {
+      "tool": "get_subskill_asset",
+      "requiredValues": {
+        "subskillName": "refill-sends-workflow",
+        "assetPath": "core/contract.v2.json"
+      },
+      "mustReadUntil": {
+        "hasMore": false
+      },
+      "validation": {
+        "supportedMajor": 2,
+        "contractVersion": "2.0.0",
+        "cacheVersion": "refill-contract-v1",
+        "contractHash": "e54ba0f80bc534fd70fd8c10c1caab109fe9a91c205cfc423f5f6735cd53fdc1"
+      }
     }
   ],
   "gateOrder": [
@@ -61,6 +77,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 +242,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 +257,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 +268,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 +305,7 @@
       "start_campaign_message_preparation",
       "same_source_copy",
       "bounded_generated_message_approval",
+      "run_scheduler_sweep",
       "wait_for_scheduler"
     ],
     "neverAutoExecute": [
@@ -271,16 +334,137 @@
   "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",
       "ready-to-schedule rows alone",
       "awaiting_scheduler_after_ready_buffer"
     ]
+  },
+  "refillContract": {
+    "contractVersion": "2.0.0",
+    "cacheVersion": "refill-contract-v1",
+    "contractHash": "e54ba0f80bc534fd70fd8c10c1caab109fe9a91c205cfc423f5f6735cd53fdc1",
+    "semanticIds": {
+      "scope": [
+        "workspace_id",
+        "target_date",
+        "sender_selectors",
+        "campaign_selectors",
+        "approval_mode",
+        "contract_identity",
+        "installed_identity"
+      ],
+      "gates": [
+        "workspace_access",
+        "approval_packet",
+        "source_family",
+        "threshold",
+        "scheduler",
+        "campaign_lifecycle",
+        "send_time",
+        "no_direct_send",
+        "one_primitive",
+        "fresh_reread",
+        "normalized_accounting",
+        "prep_circuit",
+        "terminal_truth"
+      ],
+      "states": [
+        "planning",
+        "awaiting_approval",
+        "executing",
+        "settling",
+        "replanning",
+        "terminal"
+      ],
+      "actions": [
+        "prepare_messages",
+        "approve_messages",
+        "rerun_errored_cells",
+        "start_paused_campaign",
+        "run_scheduler_sweep",
+        "scheduler_first_settle",
+        "wait_for_scheduler",
+        "wait_for_active_work",
+        "wait_for_source_import",
+        "copy_selected_source_rows",
+        "continue_signal_discovery_source",
+        "continue_sales_nav_source",
+        "continue_prospeo_source",
+        "manual_source_replenishment",
+        "refresh_paid_inmail_credits",
+        "lower_paid_inmail_threshold",
+        "switch_to_connection_lane",
+        "create_connection_campaign",
+        "next_campaign",
+        "done"
+      ],
+      "receipts": [
+        "target_plan_receipt",
+        "preparation_receipt",
+        "scheduler_receipt",
+        "run_receipt"
+      ],
+      "sideEffectClasses": [
+        "read_only",
+        "message_preparation",
+        "message_approval",
+        "source_replenishment",
+        "credit_refresh",
+        "campaign_start",
+        "scheduler_placement"
+      ],
+      "forbiddenActions": [
+        "direct_send",
+        "raw_scheduler_write",
+        "campaign_create",
+        "campaign_archive_delete",
+        "threshold_lowering",
+        "unselected_source_mutation",
+        "unapproved_campaign_start",
+        "sender_config_write"
+      ],
+      "terminalReasons": [
+        "projected_full",
+        "concrete_blocker",
+        "deadline_reached",
+        "iteration_limit",
+        "operator_stopped",
+        "capped_by_scheduler",
+        "loaded_awaiting_scheduler",
+        "lanes_exhausted",
+        "not_an_evergreen_workspace",
+        "no_refillable_campaigns"
+      ],
+      "transitions": [
+        "",
+        "",
+        "",
+        "",
+        "",
+        ""
+      ]
+    }
   }
 }

package/dist/tools/find-leads-runs.d.ts

@@ -1,151 +0,0 @@
-type FindLeadsSnapshot = {
-    runId: string;
-    leadListId?: string;
-    version?: number;
-    status: string;
-    terminal?: boolean;
-    cancelled?: boolean;
-    [key: string]: unknown;
-};
-export declare const findLeadsRunToolDefinitions: readonly [{
-    readonly name: "bootstrap_find_leads";
-    readonly description: "Create or resume a durable campaignless Find Leads run and its lead list. No campaign or workingCampaignId is required.";
-    readonly inputSchema: {
-        readonly type: "object";
-        readonly properties: {
-            readonly bootstrapKey: {
-                readonly type: "string";
-            };
-            readonly name: {
-                readonly type: "string";
-            };
-        };
-        readonly required: readonly ["bootstrapKey"];
-        readonly additionalProperties: false;
-    };
-}, {
-    readonly name: "get_find_leads_run";
-    readonly description: "Read the authoritative durable Find Leads snapshot.";
-    readonly inputSchema: {
-        readonly type: "object";
-        readonly properties: {
-            readonly runId: {
-                readonly type: "string";
-            };
-        };
-        readonly required: readonly ["runId"];
-        readonly additionalProperties: false;
-    };
-}, {
-    readonly name: "update_find_leads_run";
-    readonly description: "Persist a provider/source/import approval receipt using optimistic concurrency.";
-    readonly inputSchema: {
-        readonly type: "object";
-        readonly properties: {
-            readonly runId: {
-                readonly type: "string";
-            };
-            readonly version: {
-                readonly type: "number";
-            };
-            readonly action: {
-                readonly type: "string";
-                readonly enum: readonly ["approve_provider", "approve_source_plan", "approve_import"];
-            };
-            readonly provider: {
-                readonly type: "string";
-                readonly enum: readonly ["sales-nav", "prospeo", "signal-discovery"];
-            };
-            readonly receipt: {
-                readonly type: "object";
-            };
-        };
-        readonly required: readonly ["runId", "version", "action", "receipt"];
-        readonly additionalProperties: false;
-    };
-}, {
-    readonly name: "wait_for_find_leads_run";
-    readonly description: "Poll durable Find Leads state until it changes or reaches a terminal state. Progress notifications are optional hints only.";
-    readonly inputSchema: {
-        readonly type: "object";
-        readonly properties: {
-            readonly runId: {
-                readonly type: "string";
-            };
-            readonly timeoutMs: {
-                readonly type: "number";
-            };
-            readonly intervalMs: {
-                readonly type: "number";
-            };
-        };
-        readonly required: readonly ["runId"];
-        readonly additionalProperties: false;
-    };
-}, {
-    readonly name: "cancel_find_leads";
-    readonly description: "Cancel a mutable Find Leads run with its current version.";
-    readonly inputSchema: {
-        readonly type: "object";
-        readonly properties: {
-            readonly runId: {
-                readonly type: "string";
-            };
-            readonly version: {
-                readonly type: "number";
-            };
-        };
-        readonly required: readonly ["runId", "version"];
-        readonly additionalProperties: false;
-    };
-}, {
-    readonly name: "reissue_find_leads_watch_link";
-    readonly description: "Rotate and return a fresh one-time live Find Leads watch handoff. Old links are revoked and cannot be reconstructed.";
-    readonly inputSchema: {
-        readonly type: "object";
-        readonly properties: {
-            readonly runId: {
-                readonly type: "string";
-            };
-            readonly mode: {
-                readonly type: "string";
-                readonly enum: readonly ["claude", "codex", "hermes"];
-            };
-        };
-        readonly required: readonly ["runId"];
-        readonly additionalProperties: false;
-    };
-}];
-export declare function bootstrapFindLeads(input: {
-    bootstrapKey: string;
-    name?: string;
-}): Promise<FindLeadsSnapshot>;
-export declare function getFindLeadsRun(input: {
-    runId: string;
-}): Promise<FindLeadsSnapshot>;
-export declare function updateFindLeadsRun(input: {
-    runId: string;
-    version: number;
-    action: "approve_provider" | "approve_source_plan" | "approve_import";
-    provider?: "sales-nav" | "prospeo" | "signal-discovery";
-    receipt: Record<string, unknown>;
-}): Promise<FindLeadsSnapshot>;
-export declare function cancelFindLeads(input: {
-    runId: string;
-    version: number;
-}): Promise<FindLeadsSnapshot>;
-export declare function reissueFindLeadsWatchLink(input: {
-    runId: string;
-    mode?: "claude" | "codex" | "hermes";
-}): Promise<{
-    runId: string;
-    leadListId: string;
-    watchUrl: string;
-    expiresAt: string;
-}>;
-export declare function waitForFindLeadsRun(input: {
-    runId: string;
-    timeoutMs?: number;
-    intervalMs?: number;
-}): Promise<FindLeadsSnapshot>;
-export {};

package/dist/tools/find-leads-runs.js

@@ -1,98 +0,0 @@
-import { getApi } from "../api.js";
-import { getConfig } from "../auth.js";
-function requestOptions() {
-    const config = getConfig();
-    const workspaceId = config.activeWorkspaceId || config.workspaceId || null;
-    if (!workspaceId) {
-        throw new Error("No active Sellable workspace. Run list_workspaces then set_active_workspace and retry Find Leads.");
-    }
-    return { workspaceId };
-}
-export const findLeadsRunToolDefinitions = [
-    {
-        name: "bootstrap_find_leads",
-        description: "Create or resume a durable campaignless Find Leads run and its lead list. No campaign or workingCampaignId is required.",
-        inputSchema: {
-            type: "object",
-            properties: { bootstrapKey: { type: "string" }, name: { type: "string" } },
-            required: ["bootstrapKey"],
-            additionalProperties: false,
-        },
-    },
-    {
-        name: "get_find_leads_run",
-        description: "Read the authoritative durable Find Leads snapshot.",
-        inputSchema: { type: "object", properties: { runId: { type: "string" } }, required: ["runId"], additionalProperties: false },
-    },
-    {
-        name: "update_find_leads_run",
-        description: "Persist a provider/source/import approval receipt using optimistic concurrency.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                runId: { type: "string" }, version: { type: "number" },
-                action: { type: "string", enum: ["approve_provider", "approve_source_plan", "approve_import"] },
-                provider: { type: "string", enum: ["sales-nav", "prospeo", "signal-discovery"] },
-                receipt: { type: "object" },
-            },
-            required: ["runId", "version", "action", "receipt"],
-            additionalProperties: false,
-        },
-    },
-    {
-        name: "wait_for_find_leads_run",
-        description: "Poll durable Find Leads state until it changes or reaches a terminal state. Progress notifications are optional hints only.",
-        inputSchema: {
-            type: "object",
-            properties: { runId: { type: "string" }, timeoutMs: { type: "number" }, intervalMs: { type: "number" } },
-            required: ["runId"], additionalProperties: false,
-        },
-    },
-    {
-        name: "cancel_find_leads",
-        description: "Cancel a mutable Find Leads run with its current version.",
-        inputSchema: { type: "object", properties: { runId: { type: "string" }, version: { type: "number" } }, required: ["runId", "version"], additionalProperties: false },
-    },
-    {
-        name: "reissue_find_leads_watch_link",
-        description: "Rotate and return a fresh one-time live Find Leads watch handoff. Old links are revoked and cannot be reconstructed.",
-        inputSchema: { type: "object", properties: { runId: { type: "string" }, mode: { type: "string", enum: ["claude", "codex", "hermes"] } }, required: ["runId"], additionalProperties: false },
-    },
-];
-export async function bootstrapFindLeads(input) {
-    return getApi().post("/api/v3/find-leads/runs", input, requestOptions());
-}
-export async function getFindLeadsRun(input) {
-    return getApi().get(`/api/v3/find-leads/runs/${encodeURIComponent(input.runId)}`, requestOptions());
-}
-export async function updateFindLeadsRun(input) {
-    const kind = input.action === "approve_provider"
-        ? "provider_prompt"
-        : input.action === "approve_source_plan"
-            ? "source_plan"
-            : "import_approval";
-    const provider = input.provider?.replace(/-/g, "_");
-    return getApi().patch(`/api/v3/find-leads/runs/${encodeURIComponent(input.runId)}`, { action: "record_receipt", version: input.version, kind, receipt: input.receipt, ...(provider ? { provider } : {}) }, requestOptions());
-}
-export async function cancelFindLeads(input) {
-    return getApi().patch(`/api/v3/find-leads/runs/${encodeURIComponent(input.runId)}`, { action: "cancel", version: input.version }, requestOptions());
-}
-export async function reissueFindLeadsWatchLink(input) {
-    return getApi().post(`/api/v3/find-leads/runs/${encodeURIComponent(input.runId)}/watch-token`, { mode: input.mode ?? (process.env.CODEX_HOME ? "codex" : "claude") }, requestOptions());
-}
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-export async function waitForFindLeadsRun(input) {
-    const timeoutMs = Math.min(Math.max(input.timeoutMs ?? 55_000, 25), 55_000);
-    const intervalMs = Math.min(Math.max(input.intervalMs ?? 2_000, 1), 10_000);
-    const startedAt = Date.now();
-    let previousVersion;
-    let snapshot = await getFindLeadsRun(input);
-    while (!snapshot.terminal && !snapshot.cancelled && Date.now() - startedAt < timeoutMs) {
-        if (previousVersion !== undefined && snapshot.version !== previousVersion)
-            return snapshot;
-        previousVersion = snapshot.version;
-        await sleep(intervalMs);
-        snapshot = await getFindLeadsRun(input);
-    }
-    return snapshot;
-}

package/skills/find-leads-v2/SKILL.md

@@ -1,70 +0,0 @@
----
-name: find-leads-v2
-description: Canonical approval-gated campaignless lead sourcing state machine.
-visibility: internal
----
-
-# Find Leads V2
-
-This is the canonical campaignless workflow. The durable identity invariant is
-`runId = leadListId`. Resume from product state with `get_find_leads_run`; never
-reconstruct progress from chat memory.
-
-## Prerequisites and recovery
-
-- Call `get_auth_status`. If login is required, use `start_cli_login` and
-  `wait_for_cli_login` before retrying.
-- Require an active workspace. If none is active, use `list_workspaces` and
-  `set_active_workspace`.
-- If lifecycle tools, this prompt, or its flow asset are missing/outdated,
-  update the Sellable MCP/plugin, restart or reload the host, and retry.
-- Sales Nav requires a connected LinkedIn account with an active Sales Navigator search session.
-- Prospeo requires configured access and enough Prospeo credits for the bounded
-  plan.
-- Signal Discovery capacity must be available; otherwise wait or choose one of
-  the other providers.
-- For hiring-led targeting, start with `Prospeo` because its job-posting filters
-  are native. Run source work in the parent thread; do not dispatch custom source-scout subagents.
-
-## Durable flow
-
-1. `bootstrap_find_leads({ bootstrapKey, name })`, then show the returned watch
-   URL. On restart call `get_find_leads_run({ runId })`; if the link expired use
-   `reissue_find_leads_watch_link`. A deleted run/list is terminal: start a new
-   run only after explaining that recovery.
-2. Draft a compact source plan: target, provider, filters/signals, sample size,
-   import cap, fallback, and expected provider cost/capacity. Ask for explicit
-   source-plan approval. Persist it with `update_find_leads_run` action
-   `approve_source_plan`. This source-plan approval permits search only.
-3. Choose exactly one provider. Load `get_provider_prompt` for the selected provider only,
-   then call `preflight_find_leads_provider` with the current
-   run version and prompt/workflow hash. A prompt loaded for another run,
-   provider, or memory wildcard is invalid.
-4. Search/sample through `search_sales_nav`, `search_prospeo`, or
-   `search_signals`, always passing `findLeadsRunId` and current `runVersion`.
-   For Signal, persist the approved post selection with
-   `select_promising_posts` using the same run and tab.
-5. Present the bounded import plan and ask for a distinct import approval.
-   Persist `approve_import`; never treat source-plan approval as import approval.
-6. Call `import_leads` with exactly one target: `findLeadsRunId`. Pass the
-   current run version and provider search/tab receipt. Never pass a campaign
-   target on this path.
-7. Call `wait_for_lead_list_ready({ findLeadsRunId })` until ready, empty,
-   failed, or cancelled. Re-read the snapshot after timeout/retry.
-8. Review rows with `get_rows_minimal({ tableId: runId })`. For terminal empty
-   runs, export remains valid and returns a header-only CSV.
-9. Export with `export_table_csv({ tableId: runId })`. Do not create a second
-   export tool. Export failure must not mutate the run.
-
-An optional Add to Campaign action is only a suggestion after review when the
-user explicitly asks. It is never an automatic MCP step.
-
-## Terminal states
-
-- `failed`: show stable code, retryability, and exact next action. Resume the
-  same run when retryable.
-- `cancelled`: do not search or import again; review/export existing rows.
-- `ready` or `empty`: review and export.
-
-Progress extensions and background task protocols are optional host hints, not
-dependencies. Ordinary registered tools and the durable snapshot are enough.

package/skills/find-leads-v2/core/flow.v1.json

@@ -1,31 +0,0 @@
-{
-  "workflow": "find-leads-v2",
-  "version": 1,
-  "identity": "runId = leadListId",
-  "providers": {
-    "sales-nav": { "prompt": "sales-nav", "searchTool": "search_sales_nav" },
-    "prospeo": { "prompt": "prospeo", "searchTool": "search_prospeo" },
-    "signal-discovery": { "prompt": "signal-discovery", "searchTool": "search_signals" }
-  },
-  "invariants": [
-    "Resume every existing run with get_find_leads_run.",
-    "A current source-plan approval permits search only.",
-    "A distinct current import approval is required before materialization.",
-    "Load and preflight the selected provider only.",
-    "Export the source table with export_table_csv using tableId equal to runId."
-  ],
-  "states": [
-    { "id": "prerequisites", "tools": ["get_auth_status", "get_active_workspace"], "transitions": { "ready": "run_watch" } },
-    { "id": "run_watch", "tools": ["bootstrap_find_leads", "get_find_leads_run", "reissue_find_leads_watch_link"], "transitions": { "new": "source_plan", "resume_search": "search_sample", "resume_import": "materializing", "terminal": "review" } },
-    { "id": "source_plan", "transitions": { "drafted": "source_plan_approval" } },
-    { "id": "source_plan_approval", "tools": ["update_find_leads_run"], "transitions": { "approved": "provider_preflight", "cancel": "cancelled" } },
-    { "id": "provider_preflight", "tools": ["get_provider_prompt", "preflight_find_leads_provider"], "transitions": { "ready": "search_sample", "blocked": "failed" } },
-    { "id": "search_sample", "tools": ["search_sales_nav", "search_prospeo", "search_signals", "select_promising_posts"], "transitions": { "sampled": "import_plan_approval", "retryable_error": "provider_preflight", "cancel": "cancelled" } },
-    { "id": "import_plan_approval", "tools": ["update_find_leads_run"], "transitions": { "approved": "materializing", "revise": "source_plan", "cancel": "cancelled" } },
-    { "id": "materializing", "tools": ["import_leads", "wait_for_lead_list_ready", "get_find_leads_run"], "transitions": { "ready": "review", "empty": "review", "failed": "failed", "cancelled": "cancelled" } },
-    { "id": "review", "tools": ["get_rows_minimal"], "transitions": { "export": "export" } },
-    { "id": "export", "tools": ["export_table_csv"], "transitions": { "done": "review" } },
-    { "id": "failed", "tools": ["get_find_leads_run"], "transitions": { "retry": "provider_preflight", "export_existing": "export" } },
-    { "id": "cancelled", "tools": ["get_find_leads_run"], "transitions": { "review_existing": "review", "export_existing": "export" } }
-  ]
-}