@sellable/mcp 0.1.947 → 0.1.949

package/dist/server.js

@@ -65,6 +65,7 @@ import { advanceRefillV3Tool } from "./tools/refill-v3-advance.js";
 import { continueRefillV3Tool } from "./tools/refill-v3-continue.js";
 import { editRefillV3SelectedCampaignTool } from "./tools/refill-v3-edit-selected-campaign.js";
 import { fillRefillV3ReadyTool } from "./tools/refill-v3-fill-ready.js";
+import { projectRefillWorldStateForAgent } from "./tools/refill-v3-world-state-contract.js";
 import { getRefillV3WorldStateTool } from "./tools/refill-v3-world-state.js";
 import { refreshSenderEngagementCommand } from "./tools/refresh-sender-engagement.js";
 import { allTools } from "./tools/registry.js";
@@ -476,7 +477,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 result = await runSchedulerSweep(args);
                 break;
             case "refill_v3_world_state":
-                result = await getRefillV3WorldStateTool(args);
+                result = projectRefillWorldStateForAgent(await getRefillV3WorldStateTool(args));
                 break;
             case "refill_v3_fill_ready":
                 result = await fillRefillV3ReadyTool(args);

package/dist/tools/refill-v3-world-state-contract.d.ts

@@ -753,6 +753,423 @@ export declare const REFILL_V3_WORLD_STATE_OUTPUT_SCHEMA: Readonly<{
         };
     };
 }>;
+/**
+ * What the public tool returns to an agent. Campaign facts are per campaign,
+ * so they are listed once; each row keeps only its own eligibility. Repeating
+ * them on every row made sellable.dev's observation 114,600 chars, past the
+ * agent host's 50K MCP read limit (Sep 30). `refill_v3_continue` and the
+ * backend route keep the full per-row shape.
+ */
+export type RefillWorldStateCampaignRef = Pick<CampaignOption, "id" | "eligible" | "reason">;
+export type RefillWorldStateAgentCampaign = Omit<CampaignOption, "eligible" | "reason">;
+export type RefillWorldStateAgentRow = Omit<RefillWorldStateRow, "activeCampaigns" | "inactiveCampaigns"> & {
+    activeCampaigns: RefillWorldStateCampaignRef[];
+    inactiveCampaigns: RefillWorldStateCampaignRef[];
+};
+export type RefillWorldStateAgentResult = Omit<RefillWorldStateResult, "rows"> & {
+    campaigns: RefillWorldStateAgentCampaign[];
+    rows: RefillWorldStateAgentRow[];
+};
+export declare function projectRefillWorldStateForAgent(result: RefillWorldStateResult): RefillWorldStateAgentResult;
+export declare const REFILL_V3_WORLD_STATE_AGENT_OUTPUT_SCHEMA: Readonly<{
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["campaigns", "rows", "durationMs", "observationSideEffects"];
+    readonly properties: {
+        readonly campaigns: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: ("name" | "status" | "id" | "evidence" | "activeJob" | "supply" | "leadSourceFamily" | "lanes" | "startEligible")[];
+                readonly properties: {
+                    id: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    name: {
+                        readonly type: "string";
+                    };
+                    status: {
+                        readonly type: "string";
+                        readonly enum: readonly ["ACTIVE", "PAUSED"];
+                    };
+                    lanes: {
+                        readonly type: "array";
+                        readonly minItems: 1;
+                        readonly items: {
+                            readonly type: "string";
+                            readonly enum: readonly ["connection_invite", "paid_inmail"];
+                        };
+                    };
+                    startEligible: {
+                        readonly type: "boolean";
+                    };
+                    activeJob: {
+                        readonly type: readonly ["object", "null"];
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["id", "kind", "status"];
+                        readonly properties: {
+                            readonly id: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly kind: {
+                                readonly type: "string";
+                                readonly enum: readonly ["enrichment", "message_generation", "source_expansion", "scheduling"];
+                            };
+                            readonly status: {
+                                readonly type: "string";
+                                readonly enum: readonly ["queued", "running"];
+                            };
+                        };
+                    };
+                    supply: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["readyToSchedule", "readyForApproval", "readyForMessageGeneration", "needsEnrichment"];
+                        readonly properties: {
+                            readonly readyToSchedule: {
+                                readonly type: "integer";
+                                readonly minimum: 0;
+                            };
+                            readonly readyForApproval: {
+                                readonly type: "integer";
+                                readonly minimum: 0;
+                            };
+                            readonly readyForMessageGeneration: {
+                                readonly type: "integer";
+                                readonly minimum: 0;
+                            };
+                            readonly needsEnrichment: {
+                                readonly type: "integer";
+                                readonly minimum: 0;
+                            };
+                        };
+                    };
+                    leadSourceFamily: {
+                        readonly type: "string";
+                        readonly enum: readonly ["post_engager", "signal_discovery", "cold"];
+                    };
+                    evidence: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["evergreen", "lastActualUseAt", "lastScheduledUseAt", "effectiveness", "supplyHealth"];
+                        readonly properties: {
+                            readonly evergreen: {
+                                readonly type: "boolean";
+                            };
+                            readonly createdAt: {
+                                readonly type: readonly ["string", "null"];
+                            };
+                            readonly lastActualUseAt: {
+                                readonly type: readonly ["string", "null"];
+                            };
+                            readonly lastScheduledUseAt: {
+                                readonly type: readonly ["string", "null"];
+                            };
+                            readonly effectiveness: {
+                                readonly type: "string";
+                                readonly enum: readonly ["unknown", "low", "medium", "high"];
+                            };
+                            readonly supplyHealth: {
+                                readonly type: "string";
+                                readonly enum: readonly ["unknown", "healthy", "thin", "dry"];
+                            };
+                            readonly engagement: {
+                                readonly type: "object";
+                                readonly additionalProperties: false;
+                                readonly required: readonly ["sends", "accepted", "replied", "acceptRate", "replyRate"];
+                                readonly properties: {
+                                    readonly sends: {
+                                        readonly type: "number";
+                                        readonly minimum: 0;
+                                    };
+                                    readonly accepted: {
+                                        readonly type: "number";
+                                        readonly minimum: 0;
+                                    };
+                                    readonly replied: {
+                                        readonly type: "number";
+                                        readonly minimum: 0;
+                                    };
+                                    readonly acceptRate: {
+                                        readonly type: "number";
+                                        readonly minimum: 0;
+                                        readonly maximum: 100;
+                                    };
+                                    readonly replyRate: {
+                                        readonly type: "number";
+                                        readonly minimum: 0;
+                                        readonly maximum: 100;
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        readonly rows: {
+            readonly type: "array";
+            readonly items: {
+                readonly properties: {
+                    readonly activeCampaigns: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["id", "eligible", "reason"];
+                            readonly properties: {
+                                readonly id: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                };
+                                readonly eligible: {
+                                    readonly type: "boolean";
+                                };
+                                readonly reason: {
+                                    readonly type: readonly ["object", "null"];
+                                    readonly additionalProperties: false;
+                                    readonly required: readonly ["kind", "codes", "message"];
+                                    readonly properties: {
+                                        readonly kind: {
+                                            readonly type: "string";
+                                            readonly enum: readonly ["unavailable", "retry_required", "invalid_campaign_configuration"];
+                                        };
+                                        readonly codes: {
+                                            readonly type: "array";
+                                            readonly items: {
+                                                readonly type: "string";
+                                                readonly enum: readonly ["global_cooldown", "connection_cooldown", "paid_inmail_cooldown", "endpoint_temporarily_unavailable", "date_in_past", "no_sending_hours", "sender_disconnected", "sender_limit_reached", "daily_target_met", "no_eligible_campaign", "no_ready_supply", "sales_nav_disconnected", "insufficient_paid_credits", "paid_inmail_connection_health_recheck_required", "paid_inmail_credit_refresh_failed", "invalid_paid_configuration", "campaign_table_missing", "campaign_sequence_invalid", "source_family_unresolved", "campaign_work_in_flight"];
+                                            };
+                                        };
+                                        readonly message: {
+                                            readonly type: "string";
+                                        };
+                                        readonly resumeAt: {
+                                            readonly type: "string";
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                    readonly inactiveCampaigns: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["id", "eligible", "reason"];
+                            readonly properties: {
+                                readonly id: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                };
+                                readonly eligible: {
+                                    readonly type: "boolean";
+                                };
+                                readonly reason: {
+                                    readonly type: readonly ["object", "null"];
+                                    readonly additionalProperties: false;
+                                    readonly required: readonly ["kind", "codes", "message"];
+                                    readonly properties: {
+                                        readonly kind: {
+                                            readonly type: "string";
+                                            readonly enum: readonly ["unavailable", "retry_required", "invalid_campaign_configuration"];
+                                        };
+                                        readonly codes: {
+                                            readonly type: "array";
+                                            readonly items: {
+                                                readonly type: "string";
+                                                readonly enum: readonly ["global_cooldown", "connection_cooldown", "paid_inmail_cooldown", "endpoint_temporarily_unavailable", "date_in_past", "no_sending_hours", "sender_disconnected", "sender_limit_reached", "daily_target_met", "no_eligible_campaign", "no_ready_supply", "sales_nav_disconnected", "insufficient_paid_credits", "paid_inmail_connection_health_recheck_required", "paid_inmail_credit_refresh_failed", "invalid_paid_configuration", "campaign_table_missing", "campaign_sequence_invalid", "source_family_unresolved", "campaign_work_in_flight"];
+                                            };
+                                        };
+                                        readonly message: {
+                                            readonly type: "string";
+                                        };
+                                        readonly resumeAt: {
+                                            readonly type: "string";
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                    readonly date: {
+                        readonly type: "string";
+                        readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+                    };
+                    readonly sender: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["id", "name", "timezone"];
+                        readonly properties: {
+                            readonly id: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly name: {
+                                readonly type: "string";
+                            };
+                            readonly timezone: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                        };
+                    };
+                    readonly lane: {
+                        readonly type: "string";
+                        readonly enum: readonly ["connection_invite", "paid_inmail"];
+                    };
+                    readonly targetSlots: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                    };
+                    readonly takenSlots: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                    };
+                    readonly remainingTargetGap: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                    };
+                    readonly fillableSlotsNow: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                    };
+                    readonly blockedGap: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                    };
+                    readonly availableSlots: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                    };
+                    readonly reason: {
+                        readonly type: readonly ["object", "null"];
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["kind", "codes", "message"];
+                        readonly properties: {
+                            readonly kind: {
+                                readonly type: "string";
+                                readonly enum: readonly ["unavailable", "retry_required", "invalid_campaign_configuration"];
+                            };
+                            readonly codes: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "string";
+                                    readonly enum: readonly ["global_cooldown", "connection_cooldown", "paid_inmail_cooldown", "endpoint_temporarily_unavailable", "date_in_past", "no_sending_hours", "sender_disconnected", "sender_limit_reached", "daily_target_met", "no_eligible_campaign", "no_ready_supply", "sales_nav_disconnected", "insufficient_paid_credits", "paid_inmail_connection_health_recheck_required", "paid_inmail_credit_refresh_failed", "invalid_paid_configuration", "campaign_table_missing", "campaign_sequence_invalid", "source_family_unresolved", "campaign_work_in_flight"];
+                                };
+                            };
+                            readonly message: {
+                                readonly type: "string";
+                            };
+                            readonly resumeAt: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                    readonly paidCreditEvidence: {
+                        readonly type: readonly ["object", "null"];
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["availableCredits", "minimumRequired", "checkedAt", "fresh"];
+                        readonly properties: {
+                            readonly balance: {
+                                readonly type: readonly ["integer", "null"];
+                                readonly minimum: 0;
+                            };
+                            readonly sentSinceRefresh: {
+                                readonly type: "integer";
+                                readonly minimum: 0;
+                            };
+                            readonly safetyBuffer: {
+                                readonly type: "integer";
+                                readonly minimum: 0;
+                            };
+                            readonly availableCredits: {
+                                readonly type: readonly ["integer", "null"];
+                                readonly minimum: 0;
+                            };
+                            readonly committedScheduledPaidSends: {
+                                readonly type: "integer";
+                                readonly minimum: 0;
+                            };
+                            readonly minimumRequired: {
+                                readonly type: readonly ["integer", "null"];
+                                readonly minimum: 0;
+                            };
+                            readonly minimumRequiredSource: {
+                                readonly type: "string";
+                                readonly enum: readonly ["cell_column_config", "column_config", "request_override", "scheduler_default", "backend_policy", "missing_context_default"];
+                            };
+                            readonly placementBudget: {
+                                readonly type: readonly ["integer", "null"];
+                                readonly minimum: 0;
+                            };
+                            readonly checkedAt: {
+                                readonly type: readonly ["string", "null"];
+                            };
+                            readonly fresh: {
+                                readonly type: "boolean";
+                            };
+                        };
+                    };
+                };
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["date", "sender", "lane", "targetSlots", "takenSlots", "remainingTargetGap", "fillableSlotsNow", "blockedGap", "availableSlots", "reason", "activeCampaigns", "inactiveCampaigns"];
+            };
+        };
+        readonly durationMs: {
+            readonly type: "number";
+            readonly minimum: 0;
+        };
+        readonly observationSideEffects: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["scheduled", "placed", "sent", "campaignMutated", "approved", "enriched", "generated", "salesNavigatorActioned", "paidCreditCache"];
+            readonly properties: {
+                readonly scheduled: {
+                    readonly type: "boolean";
+                    readonly enum: readonly [false];
+                };
+                readonly placed: {
+                    readonly type: "boolean";
+                    readonly enum: readonly [false];
+                };
+                readonly sent: {
+                    readonly type: "boolean";
+                    readonly enum: readonly [false];
+                };
+                readonly campaignMutated: {
+                    readonly type: "boolean";
+                    readonly enum: readonly [false];
+                };
+                readonly approved: {
+                    readonly type: "boolean";
+                    readonly enum: readonly [false];
+                };
+                readonly enriched: {
+                    readonly type: "boolean";
+                    readonly enum: readonly [false];
+                };
+                readonly generated: {
+                    readonly type: "boolean";
+                    readonly enum: readonly [false];
+                };
+                readonly salesNavigatorActioned: {
+                    readonly type: "boolean";
+                    readonly enum: readonly [false];
+                };
+                readonly paidCreditCache: {
+                    readonly type: "string";
+                    readonly enum: readonly ["not_checked", "not_eligible", "fresh_cache_used", "refresh_started", "refreshed", "refresh_in_progress", "refresh_failed", "uncertain"];
+                };
+            };
+        };
+    };
+}>;
 /** Strict decoder shared by world-state and terminal-evidence package seams. */
 export declare function decodeRefillWorldStatePaidCreditEvidence(value: unknown): RefillWorldStatePaidCreditEvidence | null;
 /**

package/dist/tools/refill-v3-world-state-contract.js

@@ -403,9 +403,61 @@ export const REFILL_V3_WORLD_STATE_OUTPUT_SCHEMA = Object.freeze({
         },
     },
 });
-// ───────────────────────────────────────────────────────────────────────────
-// Decoder
-// ───────────────────────────────────────────────────────────────────────────
+export function projectRefillWorldStateForAgent(result) {
+    const campaigns = new Map();
+    const refs = (options) => options.map(({ eligible, reason, ...facts }) => {
+        if (!campaigns.has(facts.id))
+            campaigns.set(facts.id, facts);
+        return { id: facts.id, eligible, reason };
+    });
+    const rows = result.rows.map((row) => ({
+        ...row,
+        activeCampaigns: refs(row.activeCampaigns),
+        inactiveCampaigns: refs(row.inactiveCampaigns),
+    }));
+    return { ...result, campaigns: [...campaigns.values()], rows };
+}
+const { eligible: _eligible, reason: _reason, ...AGENT_CAMPAIGN_PROPERTIES } = CAMPAIGN_SCHEMA.properties;
+const CAMPAIGN_REF_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["id", "eligible", "reason"],
+    properties: {
+        id: CAMPAIGN_SCHEMA.properties.id,
+        eligible: CAMPAIGN_SCHEMA.properties.eligible,
+        reason: REASON_SCHEMA,
+    },
+};
+const FULL_ROW_SCHEMA = REFILL_V3_WORLD_STATE_OUTPUT_SCHEMA.properties.rows.items;
+export const REFILL_V3_WORLD_STATE_AGENT_OUTPUT_SCHEMA = Object.freeze({
+    type: "object",
+    additionalProperties: false,
+    required: ["campaigns", "rows", "durationMs", "observationSideEffects"],
+    properties: {
+        campaigns: {
+            type: "array",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: CAMPAIGN_SCHEMA.required.filter((key) => key !== "eligible" && key !== "reason"),
+                properties: AGENT_CAMPAIGN_PROPERTIES,
+            },
+        },
+        rows: {
+            type: "array",
+            items: {
+                ...FULL_ROW_SCHEMA,
+                properties: {
+                    ...FULL_ROW_SCHEMA.properties,
+                    activeCampaigns: { type: "array", items: CAMPAIGN_REF_SCHEMA },
+                    inactiveCampaigns: { type: "array", items: CAMPAIGN_REF_SCHEMA },
+                },
+            },
+        },
+        durationMs: REFILL_V3_WORLD_STATE_OUTPUT_SCHEMA.properties.durationMs,
+        observationSideEffects: REFILL_V3_WORLD_STATE_OUTPUT_SCHEMA.properties.observationSideEffects,
+    },
+});
 // ───────────────────────────────────────────────────────────────────────────
 // Decoder
 // ───────────────────────────────────────────────────────────────────────────
@@ -650,8 +702,10 @@ function decodeRow(value) {
     if (value.remainingTargetGap !== remaining ||
         value.fillableSlotsNow > remaining ||
         value.availableSlots !== value.fillableSlotsNow ||
-        value.blockedGap > remaining ||
-        (value.blockedGap > 0 && value.fillableSlotsNow !== 0)) {
+        // Partial capacity is legitimate: a rolling-week advisory can block the
+        // remainder while the scheduler still authorizes some slots now.
+        value.fillableSlotsNow + value.blockedGap >
+            remaining) {
         return null;
     }
     const sender = decodeSender(value.sender);