@sellable/mcp 0.1.511 → 0.1.512

package/dist/refill-journal.d.ts

@@ -0,0 +1,49 @@
+export declare const DRY_RUN_MARKER = "**DRY RUN \u2014 no mutations performed**";
+export declare const JOURNAL_SECTION_HEADINGS: {
+    readonly bootstrap: "## Bootstrap";
+    readonly plan: "## Plan";
+    readonly terminal: "## Terminal";
+};
+export declare function resolveRefillRunsRoot(): string;
+/**
+ * Throws on path-safety and permission failures. Callers must wrap the entire
+ * journal block and degrade to journalPath: null; journal failure must never
+ * abort a plan response.
+ */
+export declare function createRunJournal(params: {
+    workspaceId: string;
+    runId?: string;
+    dryRun: boolean;
+    now?: Date;
+}): {
+    filePath: string;
+    runId: string;
+};
+export declare function appendJournalEvent(filePath: string, block: string): void;
+/**
+ * The index is a rebuildable cache. Directory listing is the source of truth;
+ * Phase 85 appends dry-run lines, Phase 86 maintains real-run entries.
+ */
+export declare function appendIndexLine(entry: {
+    runId: string;
+    fileName: string;
+    workspaceId: string;
+    dryRun: boolean;
+    summary: string;
+}): void;
+export declare function renderBootstrapSection(params: {
+    summary: string;
+    senderSummary?: string;
+    laneSummary?: string;
+    targetSummary?: string;
+    creditSummary?: string;
+}): string;
+export declare function renderPlanSection(params: {
+    chosenSummary: string;
+    itinerarySummaries?: string[];
+    fallbackSummary?: string;
+}): string;
+export declare function renderTerminalSection(params: {
+    summary: string;
+    finalNumbers?: string;
+}): string;

package/dist/refill-journal.js

@@ -0,0 +1,134 @@
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+const REFILL_RUNS_ROOT_ENV = "SELLABLE_REFILL_RUNS_DIR";
+export const DRY_RUN_MARKER = "**DRY RUN — no mutations performed**";
+export const JOURNAL_SECTION_HEADINGS = {
+    bootstrap: "## Bootstrap",
+    plan: "## Plan",
+    terminal: "## Terminal",
+};
+function expandLeadingTilde(value) {
+    if (value === "~")
+        return os.homedir();
+    if (value.startsWith("~/") || value.startsWith("~\\")) {
+        return path.join(os.homedir(), value.slice(2));
+    }
+    return value;
+}
+function normalizeConfiguredRoot(value, label) {
+    const expanded = expandLeadingTilde(value);
+    if (!path.isAbsolute(expanded)) {
+        throw new Error(`${label} must be an absolute path.`);
+    }
+    return path.resolve(expanded);
+}
+export function resolveRefillRunsRoot() {
+    const envValue = process.env[REFILL_RUNS_ROOT_ENV]?.trim();
+    if (envValue) {
+        return normalizeConfiguredRoot(envValue, REFILL_RUNS_ROOT_ENV);
+    }
+    const home = os.homedir();
+    if (!home || !path.isAbsolute(home)) {
+        throw new Error(`Unable to resolve Sellable refill runs root: ${REFILL_RUNS_ROOT_ENV} is unset and home directory is unavailable.`);
+    }
+    return path.resolve(home, ".sellable/refill/runs");
+}
+function isPathInside(candidate, root) {
+    const relative = path.relative(root, candidate);
+    return (Boolean(relative) &&
+        !relative.startsWith("..") &&
+        !path.isAbsolute(relative));
+}
+function assertSafeRunId(runId) {
+    if (!/^[A-Za-z0-9_-]+$/.test(runId) ||
+        runId.includes("..") ||
+        runId.includes("/") ||
+        runId.includes("\\") ||
+        runId.includes("\0")) {
+        throw new Error("runId must be a safe filename segment.");
+    }
+}
+function utcBasicTimestamp(now) {
+    return `${now.toISOString().slice(0, 19).replace(/[-:]/g, "")}Z`;
+}
+function normalizeBlock(block) {
+    return block.endsWith("\n") ? block : `${block}\n`;
+}
+/**
+ * Throws on path-safety and permission failures. Callers must wrap the entire
+ * journal block and degrade to journalPath: null; journal failure must never
+ * abort a plan response.
+ */
+export function createRunJournal(params) {
+    const runId = params.runId ?? randomBytes(4).toString("hex");
+    assertSafeRunId(runId);
+    const root = resolveRefillRunsRoot();
+    fs.mkdirSync(root, { recursive: true });
+    const normalizedRoot = path.resolve(root);
+    const fileName = `${utcBasicTimestamp(params.now ?? new Date())}-${runId}${params.dryRun ? "-dry" : ""}.md`;
+    const filePath = path.resolve(normalizedRoot, fileName);
+    if (!isPathInside(filePath, normalizedRoot)) {
+        throw new Error("Resolved journal path escapes refill runs root.");
+    }
+    const startedAt = (params.now ?? new Date()).toISOString();
+    const header = [
+        `# Refill Sends Evergreen Run ${runId}`,
+        "",
+        `- Run ID: ${runId}`,
+        `- Workspace ID: ${params.workspaceId}`,
+        `- Started at: ${startedAt}`,
+        params.dryRun ? `- ${DRY_RUN_MARKER}` : null,
+        "",
+    ]
+        .filter((line) => line !== null)
+        .join("\n");
+    fs.appendFileSync(filePath, normalizeBlock(header), "utf8");
+    return { filePath, runId };
+}
+export function appendJournalEvent(filePath, block) {
+    try {
+        fs.appendFileSync(filePath, normalizeBlock(block), "utf8");
+    }
+    catch {
+        // Best effort by design.
+    }
+}
+/**
+ * The index is a rebuildable cache. Directory listing is the source of truth;
+ * Phase 85 appends dry-run lines, Phase 86 maintains real-run entries.
+ */
+export function appendIndexLine(entry) {
+    try {
+        const root = resolveRefillRunsRoot();
+        fs.mkdirSync(root, { recursive: true });
+        const marker = entry.dryRun ? " (dry)" : "";
+        fs.appendFileSync(path.join(root, "index.md"), `- ${entry.runId}${marker} [${entry.workspaceId}] ${entry.fileName} — ${entry.summary}\n`, "utf8");
+    }
+    catch {
+        // Best effort by design.
+    }
+}
+function renderLines(heading, lines) {
+    return normalizeBlock([heading, "", ...lines, ""].join("\n"));
+}
+export function renderBootstrapSection(params) {
+    return renderLines(JOURNAL_SECTION_HEADINGS.bootstrap, [
+        params.summary,
+        params.senderSummary,
+        params.laneSummary,
+        params.targetSummary,
+        params.creditSummary,
+    ].filter((line) => Boolean(line)));
+}
+export function renderPlanSection(params) {
+    return renderLines(JOURNAL_SECTION_HEADINGS.plan, [
+        `Chosen: ${params.chosenSummary}`,
+        ...(params.itinerarySummaries ?? []).map((summary) => `Next: ${summary}`),
+        params.fallbackSummary ? `Fallback: ${params.fallbackSummary}` : null,
+    ].filter((line) => Boolean(line)));
+}
+export function renderTerminalSection(params) {
+    return renderLines(JOURNAL_SECTION_HEADINGS.terminal, [params.summary, params.finalNumbers].filter((line) => Boolean(line)));
+}

package/dist/refill-local-state.d.ts

@@ -0,0 +1,31 @@
+export interface RefillLaneMemoryEntry {
+    senderId: string;
+    laneKey: string;
+    outcome: string;
+    cooldownUntil: string;
+    reason: string;
+}
+export interface RefillPassRateObservation {
+    campaignId: string;
+    enrichedCount: number;
+    passedCount: number;
+    observedAt: string;
+}
+export interface RefillRunSummaryEntry {
+    runId: string;
+    endedAt: string;
+    terminalState: string;
+    sendsLoaded: number;
+    lanesTouched: string[];
+}
+export interface RefillWorkspaceState {
+    laneMemory: RefillLaneMemoryEntry[];
+    passRates: RefillPassRateObservation[];
+    recentRuns: RefillRunSummaryEntry[];
+}
+/**
+ * Advisory hints only. A missing, stale, corrupt, or malformed file means no
+ * hints; live planner reads remain the source of correctness. Phase 85 reads
+ * this section only. Phase 86 adds the writer plus writeJsonAtomic.
+ */
+export declare function readRefillWorkspaceState(workspaceId: string): RefillWorkspaceState | null;

package/dist/refill-local-state.js

@@ -0,0 +1,96 @@
+import { getConfig } from "./auth.js";
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isStringArray(value) {
+    return (Array.isArray(value) && value.every((entry) => typeof entry === "string"));
+}
+function readString(record, key) {
+    const value = record[key];
+    return typeof value === "string" ? value : null;
+}
+function readNumber(record, key) {
+    const value = record[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function parseLaneMemoryEntry(value) {
+    if (!isRecord(value))
+        return null;
+    const senderId = readString(value, "senderId");
+    const laneKey = readString(value, "laneKey");
+    const outcome = readString(value, "outcome");
+    const cooldownUntil = readString(value, "cooldownUntil");
+    const reason = readString(value, "reason");
+    if (!senderId || !laneKey || !outcome || !cooldownUntil || !reason) {
+        return null;
+    }
+    return { senderId, laneKey, outcome, cooldownUntil, reason };
+}
+function parsePassRateObservation(value) {
+    if (!isRecord(value))
+        return null;
+    const campaignId = readString(value, "campaignId");
+    const enrichedCount = readNumber(value, "enrichedCount");
+    const passedCount = readNumber(value, "passedCount");
+    const observedAt = readString(value, "observedAt");
+    if (!campaignId ||
+        enrichedCount === null ||
+        passedCount === null ||
+        !observedAt) {
+        return null;
+    }
+    return { campaignId, enrichedCount, passedCount, observedAt };
+}
+function parseRunSummaryEntry(value) {
+    if (!isRecord(value))
+        return null;
+    const runId = readString(value, "runId");
+    const endedAt = readString(value, "endedAt");
+    const terminalState = readString(value, "terminalState");
+    const sendsLoaded = readNumber(value, "sendsLoaded");
+    const lanesTouched = value.lanesTouched;
+    if (!runId ||
+        !endedAt ||
+        !terminalState ||
+        sendsLoaded === null ||
+        !isStringArray(lanesTouched)) {
+        return null;
+    }
+    return { runId, endedAt, terminalState, sendsLoaded, lanesTouched };
+}
+function parseArray(value, parser) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((entry) => {
+        const parsed = parser(entry);
+        return parsed ? [parsed] : [];
+    });
+}
+/**
+ * Advisory hints only. A missing, stale, corrupt, or malformed file means no
+ * hints; live planner reads remain the source of correctness. Phase 85 reads
+ * this section only. Phase 86 adds the writer plus writeJsonAtomic.
+ */
+export function readRefillWorkspaceState(workspaceId) {
+    try {
+        const config = getConfig();
+        const refill = config.skillState
+            ?.refill;
+        if (!isRecord(refill) || refill.version !== 1)
+            return null;
+        const byWorkspace = refill.byWorkspace;
+        if (!isRecord(byWorkspace))
+            return null;
+        const workspaceState = byWorkspace[workspaceId];
+        if (!isRecord(workspaceState))
+            return null;
+        return {
+            laneMemory: parseArray(workspaceState.laneMemory, parseLaneMemoryEntry),
+            passRates: parseArray(workspaceState.passRates, parsePassRateObservation),
+            recentRuns: parseArray(workspaceState.recentRuns, parseRunSummaryEntry),
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/server.js

@@ -10,7 +10,9 @@ import { resolveCampaignFillRoute } from "./tools/campaign-fill-routing.js";
 import { fillCampaignHorizon } from "./tools/campaign-horizon-fill.js";
 import { cancelPrepareCampaignMessages, getPrepareCampaignMessagesStatus, startPrepareCampaignMessages, } from "./tools/campaign-message-preparation.js";
 import { getCampaignRefillState } from "./tools/campaign-refill-state.js";
+import { getEvergreenRefillPlan } from "./tools/evergreen-refill-plan.js";
 import { getRefillTargetPlan } from "./tools/refill-target-plan.js";
+import { refillSendsEvergreenCommand } from "./tools/refill-sends-evergreen.js";
 import { getSchedulerFillCapacity } from "./tools/scheduler-fill-capacity.js";
 import { getCampaignTableSchema, queueCampaignCells, recordCampaignReviewBatch, reviseMessageTemplateAndRerun, selectCampaignCells, waitForCampaignProcessing, } from "./tools/campaign-processing.js";
 import { archiveCampaign, createCampaign, duplicateCampaign, getCampaign, getCampaignMessagesPreview, getCampaigns, pauseCampaign, startCampaign, updateCampaign, updateCampaignBrief, } from "./tools/campaigns.js";
@@ -223,6 +225,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "get_campaign_refill_state":
                 result = await getCampaignRefillState(args);
                 break;
+            case "get_evergreen_refill_plan":
+                result = await getEvergreenRefillPlan(args);
+                break;
             case "get_refill_target_plan":
                 result = await getRefillTargetPlan(args);
                 break;
@@ -232,6 +237,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "refill_sends":
                 result = await executeRefillSendsCommand(args);
                 break;
+            case "refill_sends_evergreen":
+                result = refillSendsEvergreenCommand(args);
+                break;
             case "setup_evergreen_campaigns":
                 result = await setupEvergreenCampaigns(args);
                 markEvergreenSetupCampaignsDirty(args);

package/dist/tools/evergreen-refill-plan.d.ts

@@ -0,0 +1,49 @@
+type GetEvergreenRefillPlanInput = {
+    workspaceId?: string;
+    senderIds?: string[];
+    runState?: Record<string, unknown>;
+    journal?: boolean;
+    journalNote?: string;
+};
+export declare function sanitizeEvergreenRefillPlanResult(value: unknown): Record<string, unknown>;
+export declare const evergreenRefillPlanToolDefinitions: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            workspaceId: {
+                type: string;
+                description: string;
+            };
+            senderIds: {
+                type: string;
+                items: {
+                    type: string;
+                };
+            };
+            runState: {
+                type: string;
+                description: string;
+            };
+            journal: {
+                type: string;
+                description: string;
+            };
+            journalNote: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+}[];
+export declare function getEvergreenRefillPlan(input: GetEvergreenRefillPlanInput): Promise<{
+    warnings: any[];
+    journalPath: string | null;
+    text: string;
+    workspaceId: string;
+    workspaceResolution: string;
+}>;
+export {};

package/dist/tools/evergreen-refill-plan.js

@@ -0,0 +1,196 @@
+import * as path from "node:path";
+import { getApi } from "../api.js";
+import { appendIndexLine, appendJournalEvent, createRunJournal, renderBootstrapSection, renderPlanSection, renderTerminalSection, } from "../refill-journal.js";
+import { readRefillWorkspaceState } from "../refill-local-state.js";
+import { normalizeExplicitWorkspaceId, workspaceRequestOptions, } from "./workspace-context.js";
+const KNOWN_TOP_LEVEL_FIELDS = [
+    "readOnly",
+    "generatedAt",
+    "bootstrap",
+    "plans",
+    "globalActionQueue",
+    "evergreen",
+    "planRevision",
+    "stateRevision",
+    "packet",
+    "sideEffects",
+    "warnings",
+];
+// MCP mirror maintenance note:
+// Evergreen rung vocabulary restatements track canonical EVERGREEN_RUNG_ORDER in
+// src/lib/workflow-tables/refill-target-plan.ts. pr1 token checks track
+// PR1_TOKEN_REGEX in src/lib/workflow-tables/plan-revision.ts.
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function deepClone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+export function sanitizeEvergreenRefillPlanResult(value) {
+    if (!isRecord(value))
+        return {};
+    const sanitized = {};
+    for (const key of KNOWN_TOP_LEVEL_FIELDS) {
+        if (value[key] !== undefined)
+            sanitized[key] = deepClone(value[key]);
+    }
+    return sanitized;
+}
+function buildRunStateFromLocalHints(workspaceId) {
+    const state = readRefillWorkspaceState(workspaceId);
+    return {
+        version: 1,
+        senderCursors: [],
+        laneCooldowns: state?.laneMemory ?? [],
+        passRates: state?.passRates ?? [],
+    };
+}
+async function postEvergreenRefillPlan(body, workspaceId) {
+    const api = getApi();
+    const requestOptions = workspaceRequestOptions(workspaceId);
+    return requestOptions
+        ? api.post("/api/v3/mcp/evergreen-refill-plan", body, requestOptions)
+        : api.post("/api/v3/mcp/evergreen-refill-plan", body);
+}
+function planSummaryLines(result) {
+    const plans = Array.isArray(result.plans) ? result.plans : [];
+    return plans.flatMap((plan) => {
+        if (!isRecord(plan))
+            return [];
+        const itinerary = isRecord(plan.itinerary) ? plan.itinerary : null;
+        const chosen = isRecord(itinerary?.chosen) ? itinerary?.chosen : null;
+        const fallback = isRecord(itinerary?.fallback) ? itinerary?.fallback : null;
+        return [
+            `${String(plan.senderId ?? "unknown")}: ${String(chosen?.summary ?? "no chosen rung")}`,
+            fallback ? `fallback: ${String(fallback.trigger ?? "")}` : null,
+        ].filter((line) => Boolean(line));
+    });
+}
+function writeDryRunJournal(params) {
+    const created = createRunJournal({
+        workspaceId: params.workspaceId,
+        dryRun: true,
+    });
+    const bootstrap = isRecord(params.result.bootstrap)
+        ? params.result.bootstrap
+        : {};
+    appendJournalEvent(created.filePath, renderBootstrapSection({
+        summary: "Evergreen refill dry-run bootstrap",
+        senderSummary: JSON.stringify(bootstrap.senders ?? []),
+        laneSummary: JSON.stringify(bootstrap.laneOrder ?? []),
+        targetSummary: JSON.stringify(bootstrap.target ?? []),
+        creditSummary: JSON.stringify(bootstrap.paidCredit ?? []),
+    }));
+    const plans = Array.isArray(params.result.plans) ? params.result.plans : [];
+    for (const plan of plans) {
+        if (!isRecord(plan))
+            continue;
+        const itinerary = isRecord(plan.itinerary) ? plan.itinerary : {};
+        const chosen = isRecord(itinerary.chosen) ? itinerary.chosen : {};
+        const projected = Array.isArray(itinerary.projected)
+            ? itinerary.projected
+            : [];
+        const fallback = isRecord(itinerary.fallback) ? itinerary.fallback : {};
+        appendJournalEvent(created.filePath, renderPlanSection({
+            chosenSummary: String(chosen.summary ?? "No chosen rung"),
+            itinerarySummaries: projected
+                .filter(isRecord)
+                .map((entry) => String(entry.summary ?? "")),
+            fallbackSummary: String(fallback.trigger ?? ""),
+        }));
+    }
+    appendJournalEvent(created.filePath, renderTerminalSection({
+        summary: [
+            `planRevision=${String(params.result.planRevision ?? "")}`,
+            `stateRevision=${String(params.result.stateRevision ?? "")}`,
+            params.journalNote ?? null,
+        ]
+            .filter(Boolean)
+            .join(" "),
+    }));
+    appendIndexLine({
+        runId: created.runId,
+        fileName: path.basename(created.filePath),
+        workspaceId: params.workspaceId,
+        dryRun: true,
+        summary: "evergreen refill dry-run",
+    });
+    return created.filePath;
+}
+export const evergreenRefillPlanToolDefinitions = [
+    {
+        name: "get_evergreen_refill_plan",
+        description: "Read-only evergreen refill dry-run planner. It performs no mutations, does not schedule, send, approve, prepare, or refresh credits, and writes a local dry-run journal file unless journal:false is passed.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: {
+                    type: "string",
+                    description: "Explicit request-scoped workspace id.",
+                },
+                senderIds: {
+                    type: "array",
+                    items: { type: "string" },
+                },
+                runState: {
+                    type: "object",
+                    description: "Optional synthetic v1 run state. When provided, replaces local lane-memory hints.",
+                },
+                journal: {
+                    type: "boolean",
+                    description: "Set false to skip the local dry-run journal write.",
+                },
+                journalNote: {
+                    type: "string",
+                    description: "Optional note appended to the terminal journal section.",
+                },
+            },
+            required: ["workspaceId"],
+            additionalProperties: false,
+        },
+    },
+];
+export async function getEvergreenRefillPlan(input) {
+    const workspaceId = normalizeExplicitWorkspaceId(input.workspaceId);
+    if (!workspaceId) {
+        throw new Error("workspaceId is required for get_evergreen_refill_plan.");
+    }
+    const runState = input.runState !== undefined
+        ? input.runState
+        : buildRunStateFromLocalHints(workspaceId);
+    const raw = await postEvergreenRefillPlan({
+        workspaceId,
+        senderIds: input.senderIds,
+        runState,
+    }, workspaceId);
+    const sanitized = sanitizeEvergreenRefillPlanResult(raw);
+    const warnings = Array.isArray(sanitized.warnings)
+        ? [...sanitized.warnings]
+        : [];
+    let journalPath = null;
+    if (input.journal !== false) {
+        try {
+            journalPath = writeDryRunJournal({
+                workspaceId,
+                result: sanitized,
+                journalNote: input.journalNote,
+            });
+        }
+        catch {
+            warnings.push("journalWriteFailed");
+        }
+    }
+    const summary = [
+        "Evergreen refill dry-run plan:",
+        ...planSummaryLines(sanitized),
+        journalPath ? `Journal: ${journalPath}` : "Journal: not written",
+    ].join("\n");
+    return {
+        ...sanitized,
+        warnings,
+        journalPath,
+        text: summary,
+        workspaceId,
+        workspaceResolution: "explicit",
+    };
+}