@sellable/mcp 0.1.513 → 0.1.514

package/dist/refill-journal.d.ts

@@ -2,8 +2,11 @@ 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 execution: "## Execution";
+    readonly crashed: "## Crashed/Abandoned";
     readonly terminal: "## Terminal";
 };
+export declare const REFILL_RUNG_LABELS: Record<string, string>;
 export declare function resolveRefillRunsRoot(): string;
 /**
  * Throws on path-safety and permission failures. Callers must wrap the entire
@@ -43,7 +46,30 @@ export declare function renderPlanSection(params: {
     itinerarySummaries?: string[];
     fallbackSummary?: string;
 }): string;
+export declare function renderExecutionEventSection(_params: {
+    gate: string;
+    rung?: string | null;
+    planned: {
+        toolName?: string | null;
+        inputSummary?: string | null;
+        planRevision?: string | null;
+    };
+    did?: string | null;
+    outcome?: string | null;
+}): string;
+export declare function renderCrashedAbandonedSection(_params: {
+    runId: string;
+    priorGate: string;
+    decidedAt: string;
+}): string;
 export declare function renderTerminalSection(params: {
     summary: string;
     finalNumbers?: string;
+    executionNumbers?: {
+        doneReason?: string;
+        sendsLoaded?: number;
+        lanesTouched?: string[];
+        lanesStarted?: string[];
+        gateCycles?: number;
+    };
 }): string;

package/dist/refill-journal.js

@@ -7,8 +7,24 @@ export const DRY_RUN_MARKER = "**DRY RUN — no mutations performed**";
 export const JOURNAL_SECTION_HEADINGS = {
     bootstrap: "## Bootstrap",
     plan: "## Plan",
+    execution: "## Execution",
+    crashed: "## Crashed/Abandoned",
     terminal: "## Terminal",
 };
+export const REFILL_RUNG_LABELS = {
+    // Mirrors EVERGREEN_RUNG_ORDER in src/lib/workflow-tables/refill-target-plan.ts.
+    start_campaign: "start the paused campaign so ready rows can schedule",
+    approve_messages: "approve generated messages that are ready for review",
+    wait_for_active_work: "wait for active campaign work to finish",
+    enrich_more: "enrich the next batch of unenriched rows",
+    reconcile_source_copy: "copy leads already found into the campaign table",
+    add_leads_same_source: "find more leads via this campaign's original source",
+    paid_lane_fallback: "move paid InMail demand to the connection fallback lane",
+    next_campaign: "move to the next campaign in the lane",
+    wait_for_scheduler: "wait for the scheduler to pick up ready rows",
+    done: "finish the refill run",
+    rerun_errored_cells: "re-run errored enrichment/message cells",
+};
 function expandLeadingTilde(value) {
     if (value === "~")
         return os.homedir();
@@ -129,6 +145,58 @@ export function renderPlanSection(params) {
         params.fallbackSummary ? `Fallback: ${params.fallbackSummary}` : null,
     ].filter((line) => Boolean(line)));
 }
+export function renderExecutionEventSection(_params) {
+    const rungLabel = renderRungLabel(_params.rung);
+    return renderLines(`${JOURNAL_SECTION_HEADINGS.execution}: ${_params.gate} — ${rungLabel}`, [
+        renderPlannedLine(_params.planned),
+        _params.did ? `did: ${_params.did}` : null,
+        _params.outcome ? `outcome: ${_params.outcome}` : null,
+    ].filter((line) => Boolean(line)));
+}
+export function renderCrashedAbandonedSection(_params) {
+    return renderLines(JOURNAL_SECTION_HEADINGS.crashed, [
+        `Run ${_params.runId} was marked crashed/abandoned.`,
+        `Prior gate: ${_params.priorGate}`,
+        `Decided at: ${_params.decidedAt}`,
+    ]);
+}
 export function renderTerminalSection(params) {
-    return renderLines(JOURNAL_SECTION_HEADINGS.terminal, [params.summary, params.finalNumbers].filter((line) => Boolean(line)));
+    return renderLines(JOURNAL_SECTION_HEADINGS.terminal, [
+        params.summary,
+        params.finalNumbers,
+        ...renderExecutionNumbers(params.executionNumbers),
+    ].filter((line) => Boolean(line)));
+}
+function renderExecutionNumbers(numbers) {
+    if (!numbers)
+        return [];
+    return [
+        numbers.doneReason ? `doneReason: ${numbers.doneReason}` : null,
+        typeof numbers.sendsLoaded === "number"
+            ? `sendsLoaded: ${numbers.sendsLoaded}`
+            : null,
+        numbers.lanesTouched
+            ? `lanesTouched: ${numbers.lanesTouched.join(", ")}`
+            : null,
+        numbers.lanesStarted
+            ? `lanesStarted: ${numbers.lanesStarted.join(", ")}`
+            : null,
+        typeof numbers.gateCycles === "number"
+            ? `gateCycles: ${numbers.gateCycles}`
+            : null,
+    ].filter((line) => Boolean(line));
+}
+function renderRungLabel(rung) {
+    if (!rung)
+        return "unknown";
+    const label = REFILL_RUNG_LABELS[rung];
+    return label ? `${label} (${rung})` : rung;
+}
+function renderPlannedLine(planned) {
+    const segments = [
+        planned.toolName ?? "read-only",
+        planned.inputSummary,
+        planned.planRevision ? `planRevision ${planned.planRevision}` : null,
+    ].filter((segment) => Boolean(segment));
+    return `planned: ${segments.join(" — ")}`;
 }

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

@@ -23,6 +23,27 @@ export interface RefillWorkspaceState {
     passRates: RefillPassRateObservation[];
     recentRuns: RefillRunSummaryEntry[];
 }
+export declare const REFILL_RECENT_RUNS_MAX = 10;
+export type WriteJsonAtomicResult = {
+    ok: true;
+} | {
+    ok: false;
+    error?: unknown;
+};
+export type WriteRefillWorkspaceStateResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason?: "config_unreadable" | "lock_timeout" | "write_failed";
+    error?: unknown;
+};
+export interface RefillWorkspaceStateUpdate {
+    laneMemory?: RefillLaneMemoryEntry[];
+    passRates?: RefillPassRateObservation[];
+    runSummary?: RefillRunSummaryEntry;
+}
+export declare function writeJsonAtomic(filePath: string, value: unknown): WriteJsonAtomicResult;
+export declare function writeRefillWorkspaceState(workspaceId: string, update: RefillWorkspaceStateUpdate): WriteRefillWorkspaceStateResult;
 /**
  * Advisory hints only. A missing, stale, corrupt, or malformed file means no
  * hints; live planner reads remain the source of correctness. Phase 85 reads

package/dist/refill-local-state.js

@@ -1,4 +1,161 @@
-import { getConfig } from "./auth.js";
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getConfig, getConfigPath } from "./auth.js";
+export const REFILL_RECENT_RUNS_MAX = 10;
+const REFILL_CONFIG_LOCK_ATTEMPTS = 5;
+const REFILL_CONFIG_LOCK_RETRY_MS = 10;
+const REFILL_CONFIG_LOCK_STALE_MS = 10_000;
+export function writeJsonAtomic(filePath, value) {
+    let tempPath = null;
+    try {
+        const parentDir = path.dirname(filePath);
+        fs.mkdirSync(parentDir, { recursive: true });
+        tempPath = `${filePath}.tmp-${process.pid}-${randomBytes(6).toString("hex")}`;
+        fs.writeFileSync(tempPath, JSON.stringify(value, null, 2), "utf8");
+        fs.renameSync(tempPath, filePath);
+        return { ok: true };
+    }
+    catch (error) {
+        if (tempPath) {
+            try {
+                fs.unlinkSync(tempPath);
+            }
+            catch {
+                // Best effort cleanup only.
+            }
+        }
+        return { ok: false, error };
+    }
+}
+export function writeRefillWorkspaceState(workspaceId, update) {
+    const configPath = getConfigPath();
+    const lock = acquireConfigLock(configPath);
+    if (!lock.ok)
+        return lock;
+    try {
+        return writeRefillWorkspaceStateLocked(configPath, workspaceId, update);
+    }
+    finally {
+        releaseConfigLock(lock);
+    }
+}
+function writeRefillWorkspaceStateLocked(configPath, workspaceId, update) {
+    let raw = {};
+    if (fs.existsSync(configPath)) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(configPath, "utf8"));
+            raw = isRecord(parsed) ? parsed : {};
+        }
+        catch (error) {
+            if (error instanceof SyntaxError) {
+                return { ok: false, reason: "config_unreadable", error };
+            }
+            return { ok: false, reason: "write_failed", error };
+        }
+    }
+    const existingSkillState = isRecord(raw.skillState) ? raw.skillState : {};
+    const existingRefill = isRecord(existingSkillState.refill) &&
+        existingSkillState.refill.version === 1
+        ? existingSkillState.refill
+        : {};
+    const existingByWorkspace = isRecord(existingRefill.byWorkspace)
+        ? existingRefill.byWorkspace
+        : {};
+    const existingWorkspaceState = isRecord(existingByWorkspace[workspaceId])
+        ? existingByWorkspace[workspaceId]
+        : {};
+    const existingLaneMemory = parseArray(existingWorkspaceState.laneMemory, parseLaneMemoryEntry);
+    const existingPassRates = parseArray(existingWorkspaceState.passRates, parsePassRateObservation);
+    const existingRecentRuns = parseArray(existingWorkspaceState.recentRuns, parseRunSummaryEntry);
+    const nextWorkspaceState = {
+        laneMemory: update.laneMemory
+            ? upsertEntries(existingLaneMemory, update.laneMemory, (entry) => [entry.senderId, entry.laneKey].join("\0"))
+            : existingLaneMemory,
+        passRates: update.passRates
+            ? upsertEntries(existingPassRates, update.passRates, (entry) => entry.campaignId)
+            : existingPassRates,
+        recentRuns: update.runSummary
+            ? [...existingRecentRuns, update.runSummary].slice(-REFILL_RECENT_RUNS_MAX)
+            : existingRecentRuns.slice(-REFILL_RECENT_RUNS_MAX),
+    };
+    raw.skillState = {
+        ...existingSkillState,
+        refill: {
+            ...existingRefill,
+            version: 1,
+            byWorkspace: {
+                ...existingByWorkspace,
+                [workspaceId]: nextWorkspaceState,
+            },
+        },
+    };
+    const result = writeJsonAtomic(configPath, raw);
+    if (!result.ok) {
+        return { ok: false, reason: "write_failed", error: result.error };
+    }
+    return { ok: true };
+}
+function acquireConfigLock(configPath) {
+    const lockPath = `${configPath}.lock`;
+    for (let attempt = 0; attempt < REFILL_CONFIG_LOCK_ATTEMPTS; attempt += 1) {
+        try {
+            fs.mkdirSync(path.dirname(configPath), { recursive: true });
+            const fileDescriptor = fs.openSync(lockPath, "wx");
+            fs.writeSync(fileDescriptor, `${process.pid}\n`);
+            return { ok: true, fileDescriptor, lockPath };
+        }
+        catch (error) {
+            if (!isFileExistsError(error)) {
+                return { ok: false, reason: "lock_timeout", error };
+            }
+            if (isStaleConfigLock(lockPath)) {
+                try {
+                    fs.unlinkSync(lockPath);
+                    continue;
+                }
+                catch {
+                    // Fall through to bounded retry.
+                }
+            }
+            if (attempt < REFILL_CONFIG_LOCK_ATTEMPTS - 1) {
+                sleepSync(REFILL_CONFIG_LOCK_RETRY_MS);
+            }
+        }
+    }
+    return { ok: false, reason: "lock_timeout" };
+}
+function releaseConfigLock(lock) {
+    try {
+        fs.closeSync(lock.fileDescriptor);
+    }
+    catch {
+        // Best effort by design.
+    }
+    try {
+        fs.unlinkSync(lock.lockPath);
+    }
+    catch {
+        // Best effort by design.
+    }
+}
+function isFileExistsError(error) {
+    return (error !== null &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === "EEXIST");
+}
+function isStaleConfigLock(lockPath) {
+    try {
+        return (Date.now() - fs.statSync(lockPath).mtimeMs > REFILL_CONFIG_LOCK_STALE_MS);
+    }
+    catch {
+        return false;
+    }
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -66,6 +223,25 @@ function parseArray(value, parser) {
         return parsed ? [parsed] : [];
     });
 }
+function upsertEntries(existing, updates, keyForEntry) {
+    const next = [...existing];
+    const indexByKey = new Map();
+    next.forEach((entry, index) => {
+        indexByKey.set(keyForEntry(entry), index);
+    });
+    for (const update of updates) {
+        const key = keyForEntry(update);
+        const existingIndex = indexByKey.get(key);
+        if (existingIndex === undefined) {
+            indexByKey.set(key, next.length);
+            next.push(update);
+        }
+        else {
+            next[existingIndex] = update;
+        }
+    }
+    return next;
+}
 /**
  * Advisory hints only. A missing, stale, corrupt, or malformed file means no
  * hints; live planner reads remain the source of correctness. Phase 85 reads

package/dist/refill-run-client.d.ts

@@ -0,0 +1,62 @@
+export type RefillRunBlockerResult = {
+    blocker: "lease_lost";
+} | {
+    blocker: "active_run_in_progress";
+    runId: string;
+    gate?: string;
+    gateSeq?: number;
+};
+export declare function startRefillRunRemote(input: {
+    workspaceId?: string;
+    config?: unknown;
+    runState?: unknown;
+    resume?: {
+        runId: string;
+        fence: number;
+    };
+}): Promise<unknown>;
+export declare function refillRunStatus(input: {
+    workspaceId?: string;
+    runId: string;
+}): Promise<unknown>;
+export declare function heartbeatRefillRun(input: {
+    workspaceId?: string;
+    runId: string;
+    fence: number;
+}): Promise<unknown>;
+export declare function advanceRefillRunGateRemote(input: {
+    workspaceId?: string;
+    runId: string;
+    fence: number;
+    expectedSeq: number;
+    nextGate: string;
+    runState?: unknown;
+    planRevision?: string | null;
+    stateRevision?: string | null;
+    targetShapeRevision?: string | null;
+    doneReason?: string | null;
+    progress?: unknown;
+}): Promise<unknown>;
+export declare function recordRunPlanned(input: {
+    workspaceId?: string;
+    runId: string;
+    fence: number;
+    gate: string;
+    gateSeq: number;
+    planned: unknown;
+}): Promise<unknown>;
+export declare function recordRunOutcome(input: {
+    workspaceId?: string;
+    runId: string;
+    fence: number;
+    eventId: string;
+    did?: unknown;
+    outcome: unknown;
+}): Promise<unknown>;
+export declare function completeRefillRun(input: {
+    workspaceId?: string;
+    runId: string;
+    fence: number;
+    doneReason: string;
+    progress?: unknown;
+}): Promise<unknown>;

package/dist/refill-run-client.js

@@ -0,0 +1,101 @@
+import { getApi, SellableApiError } from "./api.js";
+const REFILL_RUNS_ROUTE = "/api/v3/mcp/refill-runs";
+function parseBlockerBody(body) {
+    try {
+        const parsed = JSON.parse(body);
+        if (parsed.blocker === "lease_lost") {
+            return { blocker: "lease_lost" };
+        }
+        if (parsed.blocker === "active_run_in_progress" &&
+            typeof parsed.runId === "string") {
+            return {
+                blocker: "active_run_in_progress",
+                runId: parsed.runId,
+                gate: typeof parsed.gate === "string" ? parsed.gate : undefined,
+                gateSeq: typeof parsed.gateSeq === "number" ? parsed.gateSeq : undefined,
+            };
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+async function postRefillRuns(workspaceId, body) {
+    try {
+        return await getApi().post(REFILL_RUNS_ROUTE, { workspaceId, ...body }, { workspaceId });
+    }
+    catch (error) {
+        if (error instanceof SellableApiError && error.status === 409) {
+            const blocker = parseBlockerBody(error.body);
+            if (blocker)
+                return blocker;
+        }
+        throw error;
+    }
+}
+export function startRefillRunRemote(input) {
+    return postRefillRuns(input.workspaceId, {
+        action: "start",
+        config: input.config,
+        runState: input.runState,
+        resume: input.resume,
+    });
+}
+export function refillRunStatus(input) {
+    return postRefillRuns(input.workspaceId, {
+        action: "status",
+        runId: input.runId,
+    });
+}
+export function heartbeatRefillRun(input) {
+    return postRefillRuns(input.workspaceId, {
+        action: "heartbeat",
+        runId: input.runId,
+        fence: input.fence,
+    });
+}
+export function advanceRefillRunGateRemote(input) {
+    return postRefillRuns(input.workspaceId, {
+        action: "advance-gate",
+        runId: input.runId,
+        fence: input.fence,
+        expectedSeq: input.expectedSeq,
+        nextGate: input.nextGate,
+        runState: input.runState,
+        planRevision: input.planRevision,
+        stateRevision: input.stateRevision,
+        targetShapeRevision: input.targetShapeRevision,
+        doneReason: input.doneReason,
+        progress: input.progress,
+    });
+}
+export function recordRunPlanned(input) {
+    return postRefillRuns(input.workspaceId, {
+        action: "record-planned",
+        runId: input.runId,
+        fence: input.fence,
+        gate: input.gate,
+        gateSeq: input.gateSeq,
+        planned: input.planned,
+    });
+}
+export function recordRunOutcome(input) {
+    return postRefillRuns(input.workspaceId, {
+        action: "record-outcome",
+        runId: input.runId,
+        fence: input.fence,
+        eventId: input.eventId,
+        did: input.did,
+        outcome: input.outcome,
+    });
+}
+export function completeRefillRun(input) {
+    return postRefillRuns(input.workspaceId, {
+        action: "complete",
+        runId: input.runId,
+        fence: input.fence,
+        doneReason: input.doneReason,
+        progress: input.progress,
+    });
+}

package/dist/refill-run-loop.d.ts

@@ -0,0 +1,100 @@
+import type { appendIndexLine, appendJournalEvent, createRunJournal, renderBootstrapSection, renderCrashedAbandonedSection, renderExecutionEventSection, renderPlanSection, renderTerminalSection } from "./refill-journal.js";
+import type { advanceRefillRunGateRemote, completeRefillRun, heartbeatRefillRun, recordRunOutcome, recordRunPlanned, refillRunStatus, startRefillRunRemote } from "./refill-run-client.js";
+import type { getPrepareCampaignMessagesStatus } from "./tools/campaign-message-preparation.js";
+import type { executeOneYoloPrimitive, executeStartCampaignPrimitive, prepareRowSelectorValue, refillPrepareRequestHash, refreshPaidInmailCreditsWithRetry } from "./tools/refill-executors.js";
+export type RefillLoopGate = "g0_bootstrap" | "g1_plan" | "g2_execute" | "g3_verify" | "g4_terminal";
+export interface RefillV2LoopInput {
+    workspaceId: string;
+    intent?: "auto" | "evergreen" | "plain" | "active" | string;
+    senderIds?: string[];
+    resume?: {
+        runId: string;
+        fence: number;
+    };
+    approvalMode?: "approve" | "mark_ready";
+    dryRun?: boolean;
+}
+export interface RefillV2LoopBudgets {
+    maxGateCyclesPerInvocation: number;
+    pollIntervalMs: number;
+    maxPollsPerWait: number;
+    maxSchedulerReadbacks: number;
+    waitWallClockPerInvocationMs: number;
+    schedulerWaitRunBudgetMs: number;
+}
+export interface RefillV2RunClient {
+    startRefillRunRemote: typeof startRefillRunRemote;
+    refillRunStatus: typeof refillRunStatus;
+    heartbeatRefillRun: typeof heartbeatRefillRun;
+    advanceRefillRunGateRemote: typeof advanceRefillRunGateRemote;
+    recordRunPlanned: typeof recordRunPlanned;
+    recordRunOutcome: typeof recordRunOutcome;
+    completeRefillRun: typeof completeRefillRun;
+}
+export interface RefillV2Executors {
+    executeOneYoloPrimitive: typeof executeOneYoloPrimitive;
+    executeStartCampaignPrimitive: typeof executeStartCampaignPrimitive;
+    refreshPaidInmailCreditsWithRetry: typeof refreshPaidInmailCreditsWithRetry;
+    getPrepareCampaignMessagesStatus?: typeof getPrepareCampaignMessagesStatus;
+    refillPrepareRequestHash?: typeof refillPrepareRequestHash;
+    prepareRowSelectorValue?: typeof prepareRowSelectorValue;
+}
+export interface RefillV2JournalDeps {
+    createRunJournal: typeof createRunJournal;
+    appendJournalEvent: typeof appendJournalEvent;
+    renderBootstrapSection: typeof renderBootstrapSection;
+    renderPlanSection: typeof renderPlanSection;
+    renderExecutionEventSection: typeof renderExecutionEventSection;
+    renderCrashedAbandonedSection: typeof renderCrashedAbandonedSection;
+    renderTerminalSection: typeof renderTerminalSection;
+    appendIndexLine?: typeof appendIndexLine;
+}
+export interface RefillV2LocalStateDeps {
+    writeRunSummary?: (entry: Record<string, unknown>) => void | Promise<void>;
+    writeRefillWorkspaceState?: (workspaceId: string, update: Record<string, unknown>) => unknown | Promise<unknown>;
+}
+export interface RefillV2LoopDeps {
+    runClient: RefillV2RunClient;
+    readPlan: (input: {
+        workspaceId: string;
+        intent?: string;
+        senderIds?: string[];
+        runState?: Record<string, unknown>;
+        journal?: boolean;
+    }) => Promise<Record<string, unknown>>;
+    executors: RefillV2Executors;
+    journal: RefillV2JournalDeps;
+    localState?: RefillV2LocalStateDeps;
+    budgets?: Partial<RefillV2LoopBudgets>;
+    now?: () => Date;
+    sleep?: (ms: number) => Promise<void>;
+    requestSchedulerRun?: (workspaceId: string) => Promise<unknown>;
+}
+export type RefillV2LoopResult = {
+    status: "dry_run";
+    plan: Record<string, unknown>;
+} | {
+    status: "in_progress";
+    runId: string;
+    fence: number;
+    gate: RefillLoopGate;
+    guidance: string;
+    journalPath?: string | null;
+} | {
+    status: "blocked";
+    blocker: string;
+    runId?: string;
+    fence?: number;
+    gate?: RefillLoopGate;
+    guidance: string;
+    holderRunId?: string;
+    report?: Record<string, unknown>;
+    journalPath?: string | null;
+} | {
+    status: "terminal";
+    doneReason: string;
+    report: Record<string, unknown>;
+    runId: string;
+    journalPath?: string | null;
+};
+export declare function runRefillV2Loop(input: RefillV2LoopInput, deps: RefillV2LoopDeps): Promise<RefillV2LoopResult>;