@sellable/mcp 0.1.794 → 0.1.795

package/dist/tools/campaign-processing.d.ts

@@ -493,6 +493,8 @@ type WaitInput = SchemaInput & {
     minPassedCount?: number;
     minGeneratedMessages?: number;
     templateRevision?: "current" | string;
+    /** Wait until the exact campaign table has no queued or processing cells. */
+    requireIdle?: boolean;
     timeoutMs?: number;
     intervalMs?: number;
 };
@@ -577,6 +579,7 @@ export declare const campaignProcessingToolDefinitions: ({
             minPassedCount?: undefined;
             minGeneratedMessages?: undefined;
             templateRevision?: undefined;
+            requireIdle?: undefined;
             timeoutMs?: undefined;
             intervalMs?: undefined;
             rowIds?: undefined;
@@ -654,6 +657,7 @@ export declare const campaignProcessingToolDefinitions: ({
             minPassedCount?: undefined;
             minGeneratedMessages?: undefined;
             templateRevision?: undefined;
+            requireIdle?: undefined;
             timeoutMs?: undefined;
             intervalMs?: undefined;
             rowIds?: undefined;
@@ -721,6 +725,7 @@ export declare const campaignProcessingToolDefinitions: ({
             minPassedCount?: undefined;
             minGeneratedMessages?: undefined;
             templateRevision?: undefined;
+            requireIdle?: undefined;
             timeoutMs?: undefined;
             intervalMs?: undefined;
             rowIds?: undefined;
@@ -757,6 +762,9 @@ export declare const campaignProcessingToolDefinitions: ({
                 type: string;
                 description: string;
             };
+            requireIdle: {
+                type: string;
+            };
             timeoutMs: {
                 type: string;
             };
@@ -814,6 +822,7 @@ export declare const campaignProcessingToolDefinitions: ({
             minPassedCount?: undefined;
             minGeneratedMessages?: undefined;
             templateRevision?: undefined;
+            requireIdle?: undefined;
             timeoutMs?: undefined;
             intervalMs?: undefined;
             targetConfig?: undefined;
@@ -1035,6 +1044,7 @@ export declare const campaignProcessingToolDefinitions: ({
             minPassedCount?: undefined;
             minGeneratedMessages?: undefined;
             templateRevision?: undefined;
+            requireIdle?: undefined;
             timeoutMs?: undefined;
             intervalMs?: undefined;
             rowIds?: undefined;
@@ -1067,6 +1077,7 @@ export declare function waitForCampaignProcessing(input: WaitInput): Promise<{
     currentTemplateRevisionHash: string;
     guidance: string;
     stats: WorkflowTableStats;
+    idle?: undefined;
     floors?: undefined;
     result?: undefined;
     warning?: undefined;
@@ -1078,6 +1089,7 @@ export declare function waitForCampaignProcessing(input: WaitInput): Promise<{
     elapsedMs: number;
     tableId: string;
     pollKey: string;
+    idle: boolean;
     floors: {
         minPassedCount: number | null;
         minGeneratedMessages: number | null;
@@ -1090,6 +1102,8 @@ export declare function waitForCampaignProcessing(input: WaitInput): Promise<{
         staleGeneratedMessagesCount: number;
         generatedWithoutPassCount: number;
         currentTemplateRevisionHash: string | null;
+        queuedCount: number | null;
+        processingCount: number | null;
     };
     stats: WorkflowTableStats;
     reason?: undefined;
@@ -1116,6 +1130,9 @@ export declare function waitForCampaignProcessing(input: WaitInput): Promise<{
         currentTemplateRevisionHash: string | null;
         passFloorMet: boolean;
         generatedFloorMet: boolean;
+        idle: boolean;
+        queuedCount: number | null;
+        processingCount: number | null;
     };
     recovery: {
         checkpoint: string;
@@ -1146,6 +1163,7 @@ export declare function waitForCampaignProcessing(input: WaitInput): Promise<{
     stats: WorkflowTableStats | null;
     requestedTemplateRevision?: undefined;
     currentTemplateRevisionHash?: undefined;
+    idle?: undefined;
     floors?: undefined;
     result?: undefined;
 }>;

package/dist/tools/campaign-processing.js

@@ -434,7 +434,7 @@ export const campaignProcessingToolDefinitions = [
     },
     {
         name: "wait_for_campaign_processing",
-        description: "Stats-only campaign processing wait. Use for fit/message readiness instead of wait_for_rubric_results when waiting on campaign-table processing. Generated messages are counted separately from rubric passes; current template revision is enforced through messageDraftBasis.approvedBriefHash.",
+        description: "Stats-only campaign processing wait. Use for fit/message readiness or requireIdle:true when an exact campaign table must settle before replanning. Generated messages are counted separately from rubric passes; current template revision is enforced through messageDraftBasis.approvedBriefHash.",
         inputSchema: {
             type: "object",
             properties: {
@@ -447,6 +447,7 @@ export const campaignProcessingToolDefinitions = [
                     type: "string",
                     description: '"current" (default when minGeneratedMessages is set) or an explicit current approved brief hash.',
                 },
+                requireIdle: { type: "boolean" },
                 timeoutMs: { type: "number" },
                 intervalMs: { type: "number" },
             },
@@ -603,6 +604,7 @@ function buildProcessingTimeoutRecovery({ input, schema, stats, minPassedCount,
                 ...(minPassedCount ? { minPassedCount } : {}),
                 ...(minGeneratedMessages ? { minGeneratedMessages } : {}),
                 ...(templateRevision ? { templateRevision } : {}),
+                ...(input.requireIdle ? { requireIdle: true } : {}),
             },
         });
     }
@@ -693,11 +695,13 @@ export async function waitForCampaignProcessing(input) {
         : null;
     const templateRevision = input.templateRevision ??
         (minGeneratedMessages !== null ? "current" : null);
+    const requireIdle = input.requireIdle === true;
     const pollKey = stableHash({
         tableId: schema.tableId,
         minPassedCount,
         minGeneratedMessages,
         templateRevision,
+        requireIdle,
     });
     const start = Date.now();
     let attempts = 0;
@@ -732,13 +736,19 @@ export async function waitForCampaignProcessing(input) {
             : (stats.generatedMessagesCount ?? stats.messagesCount ?? 0);
         const passFloorMet = minPassedCount === null || passed >= minPassedCount;
         const generatedFloorMet = minGeneratedMessages === null || generated >= minGeneratedMessages;
-        if (passFloorMet && generatedFloorMet) {
+        const queuedCount = typeof stats.queuedCount === "number" ? stats.queuedCount : null;
+        const processingCount = typeof stats.processingCount === "number" ? stats.processingCount : null;
+        const idle = queuedCount !== null &&
+            processingCount !== null &&
+            queuedCount + processingCount === 0;
+        if (passFloorMet && generatedFloorMet && (!requireIdle || idle)) {
             return {
                 ready: true,
                 attempts,
                 elapsedMs: Date.now() - start,
                 tableId: schema.tableId,
                 pollKey,
+                idle,
                 floors: {
                     minPassedCount,
                     minGeneratedMessages,
@@ -751,6 +761,8 @@ export async function waitForCampaignProcessing(input) {
                     staleGeneratedMessagesCount: stats.staleGeneratedMessagesCount ?? 0,
                     generatedWithoutPassCount: stats.generatedWithoutPassCount ?? 0,
                     currentTemplateRevisionHash: currentRevisionHash,
+                    queuedCount,
+                    processingCount,
                 },
                 stats,
             };
@@ -788,6 +800,11 @@ export async function waitForCampaignProcessing(input) {
             generatedFloorMet: minGeneratedMessages === null ||
                 (lastStats?.currentRevisionGeneratedMessagesCount ?? 0) >=
                     minGeneratedMessages,
+            idle: typeof lastStats?.queuedCount === "number" &&
+                typeof lastStats?.processingCount === "number" &&
+                lastStats.queuedCount + lastStats.processingCount === 0,
+            queuedCount: lastStats?.queuedCount ?? null,
+            processingCount: lastStats?.processingCount ?? null,
         },
         recovery,
         guidance: "Surface this partial validation checkpoint before taking another action. Use recovery.suggestedToolCalls to retry processing, queue missing work, revise rubrics, record a fresh same-source sample, revise source, or revise message quality instead of moving to Settings on a weak sample.",

package/dist/tools/integrations.d.ts

@@ -86,10 +86,10 @@ type IntegrationHomeWorkspacePin = {
 };
 /**
  * Mirror the home-workspace consistency invariant owned by
- * `readMcpAgentServiceContext` without importing that module into this hot tool
- * surface. `auth.ts` and `agent-service-auth.ts` remain the credential authority;
- * this local read exists only to put their already-validated HOME value into the
- * request option bag.
+ * `readMcpAgentServiceContext`. Customer profiles prove home with the customer
+ * workspace lock. Cross-workspace Admin profiles intentionally omit that lock,
+ * so their complete signed Agent service context plus the server-authenticated
+ * Admin kind proves home instead.
  *
  * The server independently enforces the same boundary. This client pin makes the
  * tool predictable while the active workspace is elsewhere; it is not the

package/dist/tools/integrations.js

@@ -1,3 +1,4 @@
+import { readMcpAgentServiceContext } from "../agent-service-auth.js";
 import { getApi, SellableApiError } from "../api.js";
 import { getConfig } from "../auth.js";
 /**
@@ -93,10 +94,10 @@ const READ_TIMEOUT_MS = 25_000;
 const CALL_TIMEOUT_MS = 45_000;
 /**
  * Mirror the home-workspace consistency invariant owned by
- * `readMcpAgentServiceContext` without importing that module into this hot tool
- * surface. `auth.ts` and `agent-service-auth.ts` remain the credential authority;
- * this local read exists only to put their already-validated HOME value into the
- * request option bag.
+ * `readMcpAgentServiceContext`. Customer profiles prove home with the customer
+ * workspace lock. Cross-workspace Admin profiles intentionally omit that lock,
+ * so their complete signed Agent service context plus the server-authenticated
+ * Admin kind proves home instead.
  *
  * The server independently enforces the same boundary. This client pin makes the
  * tool predictable while the active workspace is elsewhere; it is not the
@@ -109,7 +110,27 @@ export function resolveIntegrationHomeWorkspacePin(env = process.env, token = ge
     const workspaceId = env.SELLABLE_AGENT_WORKSPACE_ID?.trim();
     const lockWorkspaceId = env.SELLABLE_LOCK_WORKSPACE_ID?.trim();
     const requiresLock = ["1", "true", "yes"].includes((env.SELLABLE_REQUIRE_WORKSPACE_LOCK ?? "").trim().toLowerCase());
-    if (!workspaceId || workspaceId !== lockWorkspaceId || !requiresLock) {
+    let serviceContextWorkspaceId = null;
+    try {
+        serviceContextWorkspaceId =
+            readMcpAgentServiceContext(env, token)?.workspaceId ?? null;
+    }
+    catch {
+        serviceContextWorkspaceId = null;
+    }
+    const authenticatedKind = (env.SELLABLE_AGENT_SERVER_AUTHENTICATED_KIND ?? "")
+        .trim()
+        .toUpperCase();
+    const verifiedCustomerHome = Boolean(workspaceId) &&
+        workspaceId === serviceContextWorkspaceId &&
+        workspaceId === lockWorkspaceId &&
+        requiresLock;
+    const verifiedAdminHome = authenticatedKind === "ADMIN" &&
+        Boolean(workspaceId) &&
+        workspaceId === serviceContextWorkspaceId &&
+        !lockWorkspaceId &&
+        !requiresLock;
+    if (!verifiedCustomerHome && !verifiedAdminHome) {
         return {
             ok: false,
             envelope: envelope({

package/dist/tools/registry.d.ts

@@ -652,6 +652,7 @@ export declare const allTools: ({
             minPassedCount?: undefined;
             minGeneratedMessages?: undefined;
             templateRevision?: undefined;
+            requireIdle?: undefined;
             timeoutMs?: undefined;
             intervalMs?: undefined;
             rowIds?: undefined;
@@ -729,6 +730,7 @@ export declare const allTools: ({
             minPassedCount?: undefined;
             minGeneratedMessages?: undefined;
             templateRevision?: undefined;
+            requireIdle?: undefined;
             timeoutMs?: undefined;
             intervalMs?: undefined;
             rowIds?: undefined;
@@ -796,6 +798,7 @@ export declare const allTools: ({
             minPassedCount?: undefined;
             minGeneratedMessages?: undefined;
             templateRevision?: undefined;
+            requireIdle?: undefined;
             timeoutMs?: undefined;
             intervalMs?: undefined;
             rowIds?: undefined;
@@ -832,6 +835,9 @@ export declare const allTools: ({
                 type: string;
                 description: string;
             };
+            requireIdle: {
+                type: string;
+            };
             timeoutMs: {
                 type: string;
             };
@@ -889,6 +895,7 @@ export declare const allTools: ({
             minPassedCount?: undefined;
             minGeneratedMessages?: undefined;
             templateRevision?: undefined;
+            requireIdle?: undefined;
             timeoutMs?: undefined;
             intervalMs?: undefined;
             targetConfig?: undefined;
@@ -1110,6 +1117,7 @@ export declare const allTools: ({
             minPassedCount?: undefined;
             minGeneratedMessages?: undefined;
             templateRevision?: undefined;
+            requireIdle?: undefined;
             timeoutMs?: undefined;
             intervalMs?: undefined;
             rowIds?: undefined;

package/package.json

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

package/skills/refill-sends/SKILL.md

@@ -18,6 +18,7 @@ allowed-tools:
   - mcp__sellable__search_subskill_prompts
   - mcp__sellable__list_senders
   - mcp__sellable__select_campaign_cells
+  - mcp__sellable__wait_for_campaign_processing
 ---
 
 # Refill Sends
@@ -591,8 +592,16 @@ asset is the contract to load — load the prompt and that asset, verify the `v3
 compatible range, and report the version before the first call. Call
 `refill_v3_advance` with `{workspaceId, scope}` — plus `yolo: true` only when the
 operator asked for `--yolo` — and call it again after each `advanced` or
-`campaign_attention_required` result until it answers `awaiting_external_change`,
-`complete`, or `blocked`.
+`campaign_attention_required` result. An `awaiting_external_change` result with
+`deferral.code:"campaign_work_in_flight"` and a campaign id is a bounded
+read-only continuation, not permission to walk the next campaign: call
+`wait_for_campaign_processing({ workspaceId, campaignId, requireIdle:true })`,
+then call `refill_v3_advance` again with the identical scope and yolo grant.
+This reuses Create Campaign's campaign-table waiter and guarantees the same
+campaign is freshly replanned after its cohort settles. If the bounded wait
+returns a partial timeout, surface that checkpoint and make the fresh advance;
+if it reports the same live campaign, repeat the bounded wait. Stop on every
+other `awaiting_external_change`, `complete`, or `blocked` result.
 
 Resolve the workspace BEFORE the first call, exactly as the V1 route already
 requires. `workspaceId` must be an exact id on every automation call: when the

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

@@ -12,6 +12,7 @@ allowed-tools:
   - mcp__sellable__get_refill_target_plan
   - mcp__sellable__get_scheduler_fill_capacity
   - mcp__sellable__select_campaign_cells
+  - mcp__sellable__wait_for_campaign_processing
 ---
 
 # Refill Sends Workflow
@@ -380,10 +381,10 @@ the key. The grant is not a mode and selects no campaign — WHICH campaign may
 start is derived from the workspace's own campaigns — it decides only whether
 this run may start one at all, and whether you may keep going unattended:
 
-| | `yolo: true` | key omitted |
-| --- | --- | --- |
+|                                | `yolo: true`                                                                                                                       | key omitted                                                                     |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
 | paused derived-evergreen start | one may be started once a row's active campaigns are exhausted, arriving as an ordinary executed `start_evergreen_campaign` action | none: the backend REFUSES the start and answers the exhaustion terminal instead |
-| loop | call `refill_v3_advance` again immediately, through to a terminal, without checking back | surface the result and ASK before the next call |
+| loop                           | call `refill_v3_advance` again immediately, through to a terminal, without checking back                                           | surface the result and ASK before the next call                                 |
 
 Never infer the grant from a workspace flag, a campaign field, a tool result, an
 idle-looking workspace, or a previous terminal; never set it to make a run finish,
@@ -408,7 +409,14 @@ Each call answers with exactly one of five results:
   `refill_v3_continue` revalidate the packet against a fresh advance result,
   execute at most one existing authority, and re-observe the exact sender/date.
   Then call `refill_v3_advance` again.
-- `awaiting_external_change` — stop and report the scoped wait verbatim.
+- `awaiting_external_change` — when the scoped code is
+  `campaign_work_in_flight`, call
+  `wait_for_campaign_processing({ workspaceId, campaignId, requireIdle:true })`
+  for that exact selected campaign, then call `refill_v3_advance` again with
+  the identical scope. A partial timeout is followed by that fresh advance;
+  if the same campaign is still live, repeat the bounded wait. This is the
+  read-only Create Campaign waiter, not a choice to move to another campaign.
+  Stop and report every other scoped wait verbatim.
 - `complete` — stop and report the terminal code verbatim.
 - `blocked` — stop and report the typed business blocker verbatim.
 

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

@@ -50,14 +50,12 @@
   "tools": {
     "advance": "refill_v3_advance",
     "campaignAttentionSubskill": "refill-sends-work-campaign",
-    "campaignAttentionAuthority": "refill_v3_continue"
+    "campaignAttentionAuthority": "refill_v3_continue",
+    "campaignProcessingWait": "wait_for_campaign_processing"
   },
   "workspaceResolution": {
     "appliesWhen": "always, BEFORE the first advance call",
-    "allowedTools": [
-      "list_workspaces",
-      "get_active_workspace"
-    ],
+    "allowedTools": ["list_workspaces", "get_active_workspace"],
     "rules": [
       "An automation call requires an exact explicit workspaceId. Never pass a workspace NAME to refill_v3_advance and never let it fall back to the configured workspace when the operator named one.",
       "When the operator names a workspace, call list_workspaces FIRST and match that name to an exact workspaceId; pass that id on every advance call for the rest of the run.",
@@ -98,26 +96,16 @@
   "loop": {
     "call": {
       "tool": "refill_v3_advance",
-      "inputKeys": [
-        "workspaceId",
-        "scope",
-        "yolo"
-      ],
+      "inputKeys": ["workspaceId", "scope", "yolo"],
       "note": "Pass workspaceId and scope with the values the host resolved once, plus yolo:true only when the autonomy step granted it. workspaceId is the EXACT id workspaceResolution produced, never a name and never an implicit config default when the operator named a workspace. There is no mode, continuation, task receipt, retry counter, cursor, row, action, or receipt-fact input, and a call that supplies one is refused by the backend parser before any observation.",
-      "requiredInputKeys": [
-        "workspaceId",
-        "scope"
-      ]
+      "requiredInputKeys": ["workspaceId", "scope"]
     },
     "repeatWhile": [
       "advanced",
-      "campaign_attention_required"
-    ],
-    "stopOn": [
-      "awaiting_external_change",
-      "complete",
-      "blocked"
+      "campaign_attention_required",
+      "awaiting_external_change:campaign_work_in_flight_after_wait"
     ],
+    "stopOn": ["awaiting_external_change:other", "complete", "blocked"],
     "note": "Call advance again with the SAME two keys. Losing a prior result is harmless: every invocation reconstructs from fresh world state plus server-loaded authority receipts.",
     "repeatPolicy": {
       "granted": "Call advance again immediately, without checking back.",
@@ -143,18 +131,9 @@
       "alreadyExecuted": false,
       "route": {
         "subskill": "refill-sends-work-campaign",
-        "pass": [
-          "packet.scope",
-          "packet.evidence"
-        ],
+        "pass": ["packet.scope", "packet.evidence"],
         "returnThrough": "refill_v3_continue",
-        "returnInput": [
-          "workspaceId",
-          "scope",
-          "packet",
-          "decision",
-          "yolo"
-        ]
+        "returnInput": ["workspaceId", "scope", "packet", "decision", "yolo"]
       },
       "then": "call the advance tool again",
       "note": "This is the ONE model judgment in the flow. The backend already selected exactly one campaign and bounded the evidence; the subskill chooses one action from its own closed vocabulary and its deterministic authority validates, executes, and re-observes it."
@@ -168,14 +147,24 @@
         "deferral.code",
         "deferral.resumeAt"
       ],
-      "then": "stop and report the scoped wait verbatim"
+      "campaignWorkInFlight": {
+        "appliesToDeferralCode": "campaign_work_in_flight",
+        "wait": {
+          "tool": "wait_for_campaign_processing",
+          "input": {
+            "campaignId": "deferral.campaignId",
+            "workspaceId": "workspaceId",
+            "requireIdle": true
+          }
+        },
+        "then": "call the advance tool again with the identical workspaceId, scope, and yolo grant",
+        "note": "This is a bounded read-only wait inherited from Create Campaign. It holds the same campaign while its cells settle; it never authorizes selecting a sibling. A partial timeout returns to fresh advance, and the same deferral may authorize another bounded wait."
+      },
+      "then": "for any other deferral code, stop and report the scoped wait verbatim"
     },
     "complete": {
       "alreadyExecuted": false,
-      "surface": [
-        "terminal",
-        "observation"
-      ],
+      "surface": ["terminal", "observation"],
       "then": "stop and report the terminal code verbatim"
     },
     "blocked": {
@@ -204,6 +193,6 @@
     "Every advance call carried exactly workspaceId and scope.",
     "Every already-executed result was surfaced, never re-executed.",
     "Only campaign_attention_required loaded the campaign subskill.",
-    "The run stopped on the first awaiting_external_change, complete, or blocked result."
+    "campaign_work_in_flight used the bounded campaign table waiter and returned to a fresh advance before any sibling campaign; every other awaiting_external_change, complete, or blocked result stopped the run."
   ]
 }