@sellable/mcp 0.1.861 → 0.1.862-wip.phase187.20260811.3

package/dist/agent-opportunity-sequence-context.d.ts

@@ -0,0 +1,26 @@
+import type { McpAgentServiceContext } from "./agent-service-auth.js";
+export declare const OPPORTUNITY_SEQUENCE_TOOL_NAMES: readonly ["opportunity_sequence_next_page", "opportunity_sequence_enroll", "opportunity_sequence_record"];
+export type OpportunitySequenceToolName = (typeof OPPORTUNITY_SEQUENCE_TOOL_NAMES)[number];
+export type AgentOpportunitySequenceContext = Readonly<{
+    workspaceId: string;
+    agentId: string;
+    credentialId: string;
+    credentialGeneration: number;
+    runtimeGeneration: number;
+    adminGenerationId: string;
+    adminGenerationFence: string;
+}>;
+export declare const OPPORTUNITY_SEQUENCE_CONTEXT_REQUIRED_ERROR = "opportunity_sequence_current_admin_context_required";
+export declare function isOpportunitySequenceTool(name: string): name is OpportunitySequenceToolName;
+/**
+ * Actorless is deliberate for these three tools only. Authority is the
+ * credential-bound home Agent plus the immutable ADMIN runtime tuple; no tool
+ * argument participates in this resolution.
+ */
+export declare function agentOpportunitySequenceContext(name: string, principal: McpAgentServiceContext | null | undefined, env?: Record<string, string | undefined>): {
+    required: false;
+    context: null;
+} | {
+    required: true;
+    context: AgentOpportunitySequenceContext | null;
+};

package/dist/agent-opportunity-sequence-context.js

@@ -0,0 +1,48 @@
+export const OPPORTUNITY_SEQUENCE_TOOL_NAMES = Object.freeze([
+    "opportunity_sequence_next_page",
+    "opportunity_sequence_enroll",
+    "opportunity_sequence_record",
+]);
+export const OPPORTUNITY_SEQUENCE_CONTEXT_REQUIRED_ERROR = "opportunity_sequence_current_admin_context_required";
+export function isOpportunitySequenceTool(name) {
+    return OPPORTUNITY_SEQUENCE_TOOL_NAMES.includes(name);
+}
+/**
+ * Actorless is deliberate for these three tools only. Authority is the
+ * credential-bound home Agent plus the immutable ADMIN runtime tuple; no tool
+ * argument participates in this resolution.
+ */
+export function agentOpportunitySequenceContext(name, principal, env = process.env) {
+    if (!isOpportunitySequenceTool(name)) {
+        return { required: false, context: null };
+    }
+    const runtimeGeneration = Number(env.SELLABLE_AGENT_RUNTIME_GENERATION ??
+        env.SELLABLE_RUNTIME_GENERATION ??
+        "");
+    const adminGenerationId = env.SELLABLE_AGENT_ADMIN_GENERATION_ID?.trim() ?? "";
+    const adminGenerationFence = env.SELLABLE_AGENT_ADMIN_GENERATION_FENCE?.trim() ?? "";
+    const current = principal?.kind === "agent_service" &&
+        env.SELLABLE_AGENT_SERVER_AUTHENTICATED_KIND?.trim().toUpperCase() ===
+            "ADMIN" &&
+        env.SELLABLE_AGENT_WORKSPACE_ID?.trim() === principal.workspaceId &&
+        env.SELLABLE_AGENT_ID?.trim() === principal.agentId &&
+        Number(env.SELLABLE_AGENT_CREDENTIAL_GENERATION) === principal.generation &&
+        Number.isSafeInteger(runtimeGeneration) &&
+        runtimeGeneration > 0 &&
+        /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(adminGenerationId) &&
+        /^[1-9][0-9]{0,19}$/.test(adminGenerationFence);
+    return {
+        required: true,
+        context: current
+            ? {
+                workspaceId: principal.workspaceId,
+                agentId: principal.agentId,
+                credentialId: principal.credentialId,
+                credentialGeneration: principal.generation,
+                runtimeGeneration,
+                adminGenerationId,
+                adminGenerationFence,
+            }
+            : null,
+    };
+}

package/dist/agent-tool-names.d.ts

@@ -3,14 +3,14 @@
  * manifests. Keep this free of tool implementation imports so Next can bundle
  * it; registry parity is enforced in sellable-agent-tool-policy.test.ts.
  */
-export declare const SELLABLE_MCP_TOOL_NAMES: readonly ["add_column", "add_on_demand_leads", "add_rubric_item", "add_teammate", "add_to_comment_campaign", "add_to_connection_campaign", "add_to_inmail_campaign", "archive_campaign", "attach_recommended_sequence", "attach_sequence", "bootstrap_create_campaign", "bootstrap_engage", "bootstrap_engage_multi", "bootstrap_find_leads", "bulk_enrich_with_prospeo", "calculate_linkedin_hook_preview", "cancel_campaign_message_preparation", "cancel_find_leads", "cancel_lead_import", "capture_post_idea", "check_inbox_reply_eligibility", "check_rubric", "commit_blueprint", "complete_sender_research", "confirm_harvest_job_companies", "confirm_lead_list", "confirm_prospeo_company_accounts", "copy_sender_config", "create_campaign", "create_on_demand_campaign", "create_on_demand_table", "create_workflow_table", "create_workspace", "decide_agent_endpoint_proposal", "delete_column", "delete_rubric_item", "draft_rubrics", "duplicate_campaign", "enrich_with_prospeo", "export_table_csv", "export_workspace_csv", "fetch_company", "fetch_company_posts", "fetch_linkedin_posts", "fetch_linkedin_profile", "fetch_post_engagers", "fill_campaign_horizon", "get_active_workspace", "get_agent_endpoint_run", "get_agent_soul", "get_auth_status", "get_campaign", "get_campaign_context", "get_campaign_framework", "get_campaign_message_preparation_status", "get_campaign_messages_preview", "get_campaign_navigation_state", "get_campaign_refill_state", "get_campaign_table_schema", "get_campaign_waterfall", "get_campaigns", "get_column_schema", "get_company_info", "get_engage_memory", "get_engage_state", "get_engaged_posts", "get_find_leads_run", "get_inbox_thread", "get_integration_connection_status", "get_linkedin_profile", "get_or_create_direct_campaign_table", "get_post_draft", "get_post_find_leads_scout_registry", "get_post_idea", "get_prospeo_credits", "get_provider_prompt", "get_published_post", "get_refill_target_plan", "get_rows", "get_rows_minimal", "get_runtime_identity", "get_scheduler_fill_capacity", "get_sender", "get_sender_routing", "get_source_scout_registry", "get_subskill_asset", "get_subskill_prompt", "get_table_rows", "get_user_posts", "get_workspace", "import_leads", "init_on_demand_sequence", "integrations_call_tool", "integrations_describe_tool", "integrations_list_tools", "list_agent_endpoint_runs", "list_agent_endpoints", "list_column_types", "list_dnc_entries", "list_post_draft_iterations", "list_post_drafts", "list_post_ideas", "list_published_posts", "list_senders", "list_subskill_prompts", "list_tables", "list_workspaces", "load_csv_dnc_entries", "load_csv_domains", "load_csv_linkedin_leads", "lookup_sales_nav_filter", "mark_post_published", "migrate_flat_configs", "pause_campaign", "pause_direct_campaign", "pause_on_demand_campaign", "preflight_find_leads_provider", "prepare_campaign_ab_test", "publish_agent_endpoint", "queue_campaign_cells", "queue_cells", "record_campaign_review_batch", "record_engage_proven_search", "refill_sends", "refill_v3_advance", "refill_v3_continue", "refill_v3_edit_selected_campaign", "refill_v3_fill_ready", "refill_v3_world_state", "refresh_paid_inmail_credits", "refresh_sender_engagement", "reissue_find_leads_watch_link", "render_linkedin_post_preview", "reorder_columns", "resolve_campaign_fill_route", "revise_message_template_and_rerun", "rotate_agent_endpoint_key", "run_scheduler_sweep", "save_domain_filters", "save_hook_research", "save_post_draft", "save_rubrics", "search_apollo", "search_available_integrations", "search_engagement_posts", "search_harvest_jobs", "search_inbox_threads", "search_prospeo", "search_prospeo_companies", "search_sales_nav", "search_signals", "search_subskill_prompts", "select_campaign_cells", "select_necessary_rubrics", "select_promising_posts", "send_inbox_draft", "send_inbox_manual_reply", "set_active_workspace", "set_campaign_waterfall_order", "set_company_info", "set_engage_state", "set_engage_style_guide", "set_headline_icp_criteria", "set_sender_calendar_link", "set_sender_routing", "setup_evergreen_campaigns", "start_campaign", "start_campaign_message_preparation", "start_cli_login", "start_direct_campaign", "start_integration_connection", "start_on_demand_campaign", "stop_agent_endpoint_run", "update_agent_soul", "update_campaign", "update_campaign_brief", "update_cell", "update_column", "update_find_leads_run", "update_inbox_draft", "update_post_draft", "update_published_post_metrics", "update_rubric_item", "upsert_engage_tracked_person", "upsert_rubric", "validate_campaign1_kickoff_handoff", "verify_table_row", "wait_for_campaign_processing", "wait_for_campaign_table_ready", "wait_for_cli_login", "wait_for_find_leads_run", "wait_for_lead_list_ready", "wait_for_rubric_results"];
+export declare const SELLABLE_MCP_TOOL_NAMES: readonly ["add_column", "add_on_demand_leads", "add_rubric_item", "add_teammate", "add_to_comment_campaign", "add_to_connection_campaign", "add_to_inmail_campaign", "archive_campaign", "attach_recommended_sequence", "attach_sequence", "bootstrap_create_campaign", "bootstrap_engage", "bootstrap_engage_multi", "bootstrap_find_leads", "bulk_enrich_with_prospeo", "calculate_linkedin_hook_preview", "cancel_campaign_message_preparation", "cancel_find_leads", "cancel_lead_import", "capture_post_idea", "check_inbox_reply_eligibility", "check_rubric", "commit_blueprint", "complete_sender_research", "confirm_harvest_job_companies", "confirm_lead_list", "confirm_prospeo_company_accounts", "copy_sender_config", "create_campaign", "create_on_demand_campaign", "create_on_demand_table", "create_workflow_table", "create_workspace", "decide_agent_endpoint_proposal", "delete_column", "delete_rubric_item", "draft_rubrics", "duplicate_campaign", "enrich_with_prospeo", "export_table_csv", "export_workspace_csv", "fetch_company", "fetch_company_posts", "fetch_linkedin_posts", "fetch_linkedin_profile", "fetch_post_engagers", "fill_campaign_horizon", "get_active_workspace", "get_agent_endpoint_run", "get_agent_soul", "get_auth_status", "get_campaign", "get_campaign_context", "get_campaign_framework", "get_campaign_message_preparation_status", "get_campaign_messages_preview", "get_campaign_navigation_state", "get_campaign_refill_state", "get_campaign_table_schema", "get_campaign_waterfall", "get_campaigns", "get_column_schema", "get_company_info", "get_engage_memory", "get_engage_state", "get_engaged_posts", "get_find_leads_run", "get_inbox_thread", "get_integration_connection_status", "get_linkedin_profile", "get_or_create_direct_campaign_table", "get_post_draft", "get_post_find_leads_scout_registry", "get_post_idea", "get_prospeo_credits", "get_provider_prompt", "get_published_post", "get_refill_target_plan", "get_rows", "get_rows_minimal", "get_runtime_identity", "get_scheduler_fill_capacity", "get_sender", "get_sender_routing", "get_source_scout_registry", "get_subskill_asset", "get_subskill_prompt", "get_table_rows", "get_user_posts", "get_workspace", "import_leads", "init_on_demand_sequence", "integrations_call_tool", "integrations_describe_tool", "integrations_list_tools", "list_agent_endpoint_runs", "list_agent_endpoints", "list_column_types", "list_dnc_entries", "list_post_draft_iterations", "list_post_drafts", "list_post_ideas", "list_published_posts", "list_senders", "list_subskill_prompts", "list_tables", "list_workspaces", "load_csv_dnc_entries", "load_csv_domains", "load_csv_linkedin_leads", "lookup_sales_nav_filter", "mark_post_published", "migrate_flat_configs", "opportunity_sequence_enroll", "opportunity_sequence_next_page", "opportunity_sequence_record", "pause_campaign", "pause_direct_campaign", "pause_on_demand_campaign", "preflight_find_leads_provider", "prepare_campaign_ab_test", "publish_agent_endpoint", "queue_campaign_cells", "queue_cells", "record_campaign_review_batch", "record_engage_proven_search", "refill_sends", "refill_v3_advance", "refill_v3_continue", "refill_v3_edit_selected_campaign", "refill_v3_fill_ready", "refill_v3_world_state", "refresh_paid_inmail_credits", "refresh_sender_engagement", "reissue_find_leads_watch_link", "render_linkedin_post_preview", "reorder_columns", "resolve_campaign_fill_route", "revise_message_template_and_rerun", "rotate_agent_endpoint_key", "run_scheduler_sweep", "save_domain_filters", "save_hook_research", "save_post_draft", "save_rubrics", "search_apollo", "search_available_integrations", "search_engagement_posts", "search_harvest_jobs", "search_inbox_threads", "search_prospeo", "search_prospeo_companies", "search_sales_nav", "search_signals", "search_subskill_prompts", "select_campaign_cells", "select_necessary_rubrics", "select_promising_posts", "send_inbox_draft", "send_inbox_manual_reply", "set_active_workspace", "set_campaign_waterfall_order", "set_company_info", "set_engage_state", "set_engage_style_guide", "set_headline_icp_criteria", "set_sender_calendar_link", "set_sender_routing", "setup_evergreen_campaigns", "start_campaign", "start_campaign_message_preparation", "start_cli_login", "start_direct_campaign", "start_integration_connection", "start_on_demand_campaign", "stop_agent_endpoint_run", "update_agent_soul", "update_campaign", "update_campaign_brief", "update_cell", "update_column", "update_find_leads_run", "update_inbox_draft", "update_post_draft", "update_published_post_metrics", "update_rubric_item", "upsert_engage_tracked_person", "upsert_rubric", "validate_campaign1_kickoff_handoff", "verify_table_row", "wait_for_campaign_processing", "wait_for_campaign_table_ready", "wait_for_cli_login", "wait_for_find_leads_run", "wait_for_lead_list_ready", "wait_for_rubric_results"];
 /**
  * Explicit mutation classification lives beside (but outside) the flat tool
  * registry. Neither this list nor `isMutatingTool` is an input to
  * `compileAgentToolPolicy`, so editing it cannot move the fleet-pinned
  * `policyHash`.
  */
-export declare const MUTATING_TOOL_NAMES: readonly ["publish_agent_endpoint", "rotate_agent_endpoint_key", "decide_agent_endpoint_proposal", "stop_agent_endpoint_run", "pause_campaign", "archive_campaign", "update_campaign", "fill_campaign_horizon", "set_campaign_waterfall_order", "set_sender_routing", "send_inbox_draft", "send_inbox_manual_reply", "load_csv_dnc_entries", "update_cell", "queue_cells", "check_rubric", "queue_campaign_cells", "start_campaign_message_preparation", "refill_v3_fill_ready", "refill_v3_edit_selected_campaign", "refill_v3_advance", "refill_v3_continue"];
+export declare const MUTATING_TOOL_NAMES: readonly ["publish_agent_endpoint", "rotate_agent_endpoint_key", "decide_agent_endpoint_proposal", "stop_agent_endpoint_run", "pause_campaign", "archive_campaign", "update_campaign", "fill_campaign_horizon", "set_campaign_waterfall_order", "set_sender_routing", "send_inbox_draft", "send_inbox_manual_reply", "load_csv_dnc_entries", "update_cell", "queue_cells", "check_rubric", "queue_campaign_cells", "start_campaign_message_preparation", "opportunity_sequence_enroll", "opportunity_sequence_record", "refill_v3_fill_ready", "refill_v3_edit_selected_campaign", "refill_v3_advance", "refill_v3_continue"];
 export declare function isMutatingTool(name: string): boolean;
 export declare const CROSS_WORKSPACE_EXPLICIT_WORKSPACE_REQUIRED: {
     readonly code: "cross_workspace_explicit_workspace_required";

package/dist/agent-tool-names.js

@@ -117,6 +117,9 @@ export const SELLABLE_MCP_TOOL_NAMES = [
     "lookup_sales_nav_filter",
     "mark_post_published",
     "migrate_flat_configs",
+    "opportunity_sequence_enroll",
+    "opportunity_sequence_next_page",
+    "opportunity_sequence_record",
     "pause_campaign",
     "pause_direct_campaign",
     "pause_on_demand_campaign",
@@ -225,6 +228,10 @@ export const MUTATING_TOOL_NAMES = [
     "check_rubric",
     "queue_campaign_cells",
     "start_campaign_message_preparation",
+    // Phase 187: these two mutations are home-bound to the current ADMIN
+    // service principal. server.ts exempts only them from caller workspace proof.
+    "opportunity_sequence_enroll",
+    "opportunity_sequence_record",
     // Phase 146.5 Plan 08: the bounded Refill V3 mutation. Its sibling
     // `refill_v3_world_state` is an OBSERVATION and deliberately stays out.
     "refill_v3_fill_ready",

package/dist/server.js

@@ -5,6 +5,7 @@ import { HttpAgentApprovalEffectPort } from "./agent-approval-effect-port.js";
 import { AGENT_INTEGRATION_CONTEXT_REQUIRED_ERROR, agentIntegrationRequestActor, } from "./agent-integration-request-context.js";
 import { ensureAgentScope, getAgentScope, hasRecordedAgentScope, } from "./agent-scope.js";
 import { createMcpCredentialBoundary, resolveMcpCredentialIntent, } from "./agent-service-auth.js";
+import { agentOpportunitySequenceContext } from "./agent-opportunity-sequence-context.js";
 import { crossWorkspaceMutationRefusal } from "./agent-tool-names.js";
 import { compileAgentToolPolicy, createAgentMcpAuthorizationHandlers, } from "./agent-tool-policy.js";
 import { getApi } from "./api.js";
@@ -50,6 +51,7 @@ import { cancelLeadImport, confirmLeadList, confirmProspeoCompanyAccounts, getPr
 import { fetchCompany, fetchCompanyPosts, fetchLinkedInPosts, fetchLinkedInProfile, fetchPostEngagers, getLinkedInProfile, getUserPosts, } from "./tools/linkedin.js";
 import { getCampaignNavigationState } from "./tools/navigation.js";
 import { addOnDemandLeads, createOnDemandCampaign, createOnDemandTable, initOnDemandSequence, pauseOnDemandCampaign, startOnDemandCampaign, } from "./tools/one-off.js";
+import { opportunitySequenceEnroll, opportunitySequenceNextPage, opportunitySequenceRecord, } from "./tools/opportunity-sequences.js";
 import { upsertRubric } from "./tools/processing.js";
 import { completeSenderResearch, getPostFindLeadsScoutRegistry, getSourceScoutRegistry, getSubskillAsset, getSubskillPrompt, listSubskillPrompts, searchSubskillPrompts, } from "./tools/prompts.js";
 import { preflightFindLeadsProvider } from "./tools/provider-preflight.js";
@@ -201,6 +203,25 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ],
             };
         }
+        const sequenceResolution = agentOpportunitySequenceContext(name, boundary.mode === "agent_service" &&
+            boundary.context?.principal?.kind === "agent_service"
+            ? boundary.context.principal
+            : null);
+        if (sequenceResolution.required && !sequenceResolution.context) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            ok: false,
+                            error: "opportunity_sequence_current_admin_context_required",
+                            decision: "DENY",
+                        }),
+                    },
+                ],
+            };
+        }
         let agentEffectId;
         if (boundary.mode === "agent_service") {
             const authorization = boundary.authorization;
@@ -223,15 +244,25 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 };
             }
             if (boundary.context?.principal?.kind !== "endpoint_run") {
-                if (!hasRecordedAgentScope()) {
-                    await ensureAgentScope(() => getApi().get("/api/v3/workspaces"));
+                // These two mutations are pinned to the credential-derived home ADMIN
+                // context above. No model workspace selector exists, so only this exact
+                // pair bypasses the generic cross-workspace explicit-selector guard.
+                const homeBoundSequenceMutation = sequenceResolution.context !== null &&
+                    (name === "opportunity_sequence_enroll" ||
+                        name === "opportunity_sequence_record");
+                if (!homeBoundSequenceMutation) {
+                    if (!hasRecordedAgentScope()) {
+                        await ensureAgentScope(() => getApi().get("/api/v3/workspaces"));
+                    }
                 }
-                const workspaceRefusal = crossWorkspaceMutationRefusal({
-                    scope: getAgentScope(),
-                    toolName: name,
-                    workspaceBinding: authorization.policy?.workspaceBinding,
-                    args,
-                });
+                const workspaceRefusal = homeBoundSequenceMutation
+                    ? null
+                    : crossWorkspaceMutationRefusal({
+                        scope: getAgentScope(),
+                        toolName: name,
+                        workspaceBinding: authorization.policy?.workspaceBinding,
+                        args,
+                    });
                 if (workspaceRefusal) {
                     return {
                         isError: true,
@@ -733,6 +764,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "init_one_off_sequence":
                 result = await initOnDemandSequence(args);
                 break;
+            case "opportunity_sequence_next_page":
+                result = await opportunitySequenceNextPage(args, sequenceResolution.context);
+                break;
+            case "opportunity_sequence_enroll":
+                result = await opportunitySequenceEnroll(args, sequenceResolution.context);
+                break;
+            case "opportunity_sequence_record":
+                result = await opportunitySequenceRecord(args, sequenceResolution.context);
+                break;
             case "add_to_inmail_campaign":
                 result = await addToInmailCampaign(args);
                 break;

package/dist/tools/opportunity-sequences.d.ts

@@ -0,0 +1,232 @@
+import type { AgentOpportunitySequenceContext } from "../agent-opportunity-sequence-context.js";
+export declare const OPPORTUNITY_SEQUENCE_RESULT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly ok: {
+            readonly type: "boolean";
+        };
+        readonly error: {
+            readonly type: readonly ["string", "null"];
+        };
+        readonly result: {};
+    };
+    readonly required: readonly ["ok", "error", "result"];
+    readonly additionalProperties: false;
+};
+export declare const opportunitySequenceToolDefinitions: readonly [{
+    readonly name: "opportunity_sequence_next_page";
+    readonly description: "Read one bounded page of server-selected Lightfield sequence candidates, due work, and exact inbound transitions. Finish a returned continuation before starting a new checkpoint scan.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly continuation: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 8192;
+            };
+            readonly checkpoint: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 8192;
+            };
+            readonly limit: {
+                readonly type: "integer";
+                readonly minimum: 1;
+                readonly maximum: 50;
+            };
+        };
+        readonly required: readonly [];
+        readonly additionalProperties: false;
+    };
+    readonly outputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly ok: {
+                readonly type: "boolean";
+            };
+            readonly error: {
+                readonly type: readonly ["string", "null"];
+            };
+            readonly result: {};
+        };
+        readonly required: readonly ["ok", "error", "result"];
+        readonly additionalProperties: false;
+    };
+    readonly annotations: {
+        readonly title: "Read next Opportunity sequence page";
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+}, {
+    readonly name: "opportunity_sequence_enroll";
+    readonly description: "Idempotently enroll exactly one server-issued Lightfield candidate. The token binds opportunity, contact, trigger, playbook, and source facts; no caller selector is accepted.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly candidateToken: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 8192;
+            };
+        };
+        readonly required: readonly ["candidateToken"];
+        readonly additionalProperties: false;
+    };
+    readonly outputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly ok: {
+                readonly type: "boolean";
+            };
+            readonly error: {
+                readonly type: readonly ["string", "null"];
+            };
+            readonly result: {};
+        };
+        readonly required: readonly ["ok", "error", "result"];
+        readonly additionalProperties: false;
+    };
+    readonly annotations: {
+        readonly title: "Enroll Opportunity sequence candidate";
+        readonly readOnlyHint: false;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+}, {
+    readonly name: "opportunity_sequence_record";
+    readonly description: "Validate one bounded Hermes output against a server-issued work token, reconcile the provider artifact/event identity, append structured Lightfield history first, and then repair the Opportunity projection.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly workToken: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 8192;
+            };
+            readonly output: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly playbook_ref: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly maxLength: 256;
+                    };
+                    readonly playbook_hash: {
+                        readonly type: "string";
+                        readonly pattern: "^[a-f0-9]{64}$";
+                    };
+                    readonly step_id: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly maxLength: 128;
+                    };
+                    readonly source_event_ids: {
+                        readonly type: "array";
+                        readonly minItems: 1;
+                        readonly maxItems: 100;
+                        readonly uniqueItems: true;
+                        readonly items: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                            readonly maxLength: 128;
+                        };
+                    };
+                    readonly source_fingerprint: {
+                        readonly type: "string";
+                        readonly pattern: "^[a-f0-9]{64}$";
+                    };
+                    readonly artifact_type: {
+                        readonly type: "string";
+                        readonly enum: readonly ["email", "linkedin", "call_request", "same_channel_reply"];
+                    };
+                    readonly target: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly contact_id: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                                readonly maxLength: 128;
+                            };
+                            readonly channel: {
+                                readonly type: "string";
+                                readonly enum: readonly ["email", "linkedin", "phone"];
+                            };
+                            readonly address: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                                readonly maxLength: 320;
+                            };
+                        };
+                        readonly required: readonly ["contact_id", "channel"];
+                        readonly additionalProperties: false;
+                    };
+                    readonly due_at: {
+                        readonly type: "string";
+                        readonly format: "date-time";
+                    };
+                    readonly subject: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly maxLength: 200;
+                    };
+                    readonly body: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly maxLength: 4000;
+                    };
+                    readonly rationale_summary: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly maxLength: 600;
+                    };
+                };
+                readonly required: readonly ["playbook_ref", "playbook_hash", "step_id", "source_event_ids", "source_fingerprint", "artifact_type", "target", "due_at", "body", "rationale_summary"];
+                readonly additionalProperties: false;
+            };
+        };
+        readonly required: readonly ["workToken", "output"];
+        readonly additionalProperties: false;
+    };
+    readonly outputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly ok: {
+                readonly type: "boolean";
+            };
+            readonly error: {
+                readonly type: readonly ["string", "null"];
+            };
+            readonly result: {};
+        };
+        readonly required: readonly ["ok", "error", "result"];
+        readonly additionalProperties: false;
+    };
+    readonly annotations: {
+        readonly title: "Record Opportunity sequence work";
+        readonly readOnlyHint: false;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+}];
+type SequenceEnvelope = {
+    ok: boolean;
+    error: string | null;
+    result: unknown;
+};
+export declare function opportunitySequenceNextPage(args: {
+    continuation?: string;
+    checkpoint?: string;
+    limit?: number;
+}, context: AgentOpportunitySequenceContext | null): Promise<SequenceEnvelope>;
+export declare function opportunitySequenceEnroll(args: {
+    candidateToken: string;
+}, context: AgentOpportunitySequenceContext | null): Promise<SequenceEnvelope>;
+export declare function opportunitySequenceRecord(args: {
+    workToken: string;
+    output: Record<string, unknown>;
+}, context: AgentOpportunitySequenceContext | null): Promise<SequenceEnvelope>;
+export {};

package/dist/tools/opportunity-sequences.js

@@ -0,0 +1,181 @@
+import { getApi, SellableApiError } from "../api.js";
+const PATH = "/api/v3/sellable-agent/opportunity-sequences";
+const TIMEOUT_MS = 25_000;
+const MAX_RESPONSE_BYTES = 256_000;
+export const OPPORTUNITY_SEQUENCE_RESULT_SCHEMA = {
+    type: "object",
+    properties: {
+        ok: { type: "boolean" },
+        error: { type: ["string", "null"] },
+        result: {},
+    },
+    required: ["ok", "error", "result"],
+    additionalProperties: false,
+};
+export const opportunitySequenceToolDefinitions = [
+    {
+        name: "opportunity_sequence_next_page",
+        description: "Read one bounded page of server-selected Lightfield sequence candidates, due work, and exact inbound transitions. Finish a returned continuation before starting a new checkpoint scan.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                continuation: { type: "string", minLength: 1, maxLength: 8192 },
+                checkpoint: { type: "string", minLength: 1, maxLength: 8192 },
+                limit: { type: "integer", minimum: 1, maximum: 50 },
+            },
+            required: [],
+            additionalProperties: false,
+        },
+        outputSchema: OPPORTUNITY_SEQUENCE_RESULT_SCHEMA,
+        annotations: {
+            title: "Read next Opportunity sequence page",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: "opportunity_sequence_enroll",
+        description: "Idempotently enroll exactly one server-issued Lightfield candidate. The token binds opportunity, contact, trigger, playbook, and source facts; no caller selector is accepted.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                candidateToken: { type: "string", minLength: 1, maxLength: 8192 },
+            },
+            required: ["candidateToken"],
+            additionalProperties: false,
+        },
+        outputSchema: OPPORTUNITY_SEQUENCE_RESULT_SCHEMA,
+        annotations: {
+            title: "Enroll Opportunity sequence candidate",
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: "opportunity_sequence_record",
+        description: "Validate one bounded Hermes output against a server-issued work token, reconcile the provider artifact/event identity, append structured Lightfield history first, and then repair the Opportunity projection.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workToken: { type: "string", minLength: 1, maxLength: 8192 },
+                output: {
+                    type: "object",
+                    properties: {
+                        playbook_ref: { type: "string", minLength: 1, maxLength: 256 },
+                        playbook_hash: {
+                            type: "string",
+                            pattern: "^[a-f0-9]{64}$",
+                        },
+                        step_id: { type: "string", minLength: 1, maxLength: 128 },
+                        source_event_ids: {
+                            type: "array",
+                            minItems: 1,
+                            maxItems: 100,
+                            uniqueItems: true,
+                            items: { type: "string", minLength: 1, maxLength: 128 },
+                        },
+                        source_fingerprint: {
+                            type: "string",
+                            pattern: "^[a-f0-9]{64}$",
+                        },
+                        artifact_type: {
+                            type: "string",
+                            enum: [
+                                "email",
+                                "linkedin",
+                                "call_request",
+                                "same_channel_reply",
+                            ],
+                        },
+                        target: {
+                            type: "object",
+                            properties: {
+                                contact_id: { type: "string", minLength: 1, maxLength: 128 },
+                                channel: {
+                                    type: "string",
+                                    enum: ["email", "linkedin", "phone"],
+                                },
+                                address: { type: "string", minLength: 1, maxLength: 320 },
+                            },
+                            required: ["contact_id", "channel"],
+                            additionalProperties: false,
+                        },
+                        due_at: { type: "string", format: "date-time" },
+                        subject: { type: "string", minLength: 1, maxLength: 200 },
+                        body: { type: "string", minLength: 1, maxLength: 4000 },
+                        rationale_summary: {
+                            type: "string",
+                            minLength: 1,
+                            maxLength: 600,
+                        },
+                    },
+                    required: [
+                        "playbook_ref",
+                        "playbook_hash",
+                        "step_id",
+                        "source_event_ids",
+                        "source_fingerprint",
+                        "artifact_type",
+                        "target",
+                        "due_at",
+                        "body",
+                        "rationale_summary",
+                    ],
+                    additionalProperties: false,
+                },
+            },
+            required: ["workToken", "output"],
+            additionalProperties: false,
+        },
+        outputSchema: OPPORTUNITY_SEQUENCE_RESULT_SCHEMA,
+        annotations: {
+            title: "Record Opportunity sequence work",
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    },
+];
+function refusal(code) {
+    return { ok: false, error: code, result: null };
+}
+async function call(body, context) {
+    if (!context) {
+        return refusal("opportunity_sequence_current_admin_context_required");
+    }
+    try {
+        return await getApi().post(PATH, { ...body, runtimeContext: context }, {
+            workspaceId: context.workspaceId,
+            timeoutMs: TIMEOUT_MS,
+            maxResponseBytes: MAX_RESPONSE_BYTES,
+        });
+    }
+    catch (error) {
+        if (error instanceof SellableApiError) {
+            try {
+                const parsed = JSON.parse(error.body);
+                return refusal(typeof parsed.error === "string"
+                    ? parsed.error
+                    : "opportunity_sequence_request_failed");
+            }
+            catch {
+                return refusal("opportunity_sequence_request_failed");
+            }
+        }
+        return refusal("opportunity_sequence_request_failed");
+    }
+}
+export function opportunitySequenceNextPage(args, context) {
+    return call({ action: "NEXT_PAGE", ...args }, context);
+}
+export function opportunitySequenceEnroll(args, context) {
+    return call({ action: "ENROLL", candidateToken: args.candidateToken }, context);
+}
+export function opportunitySequenceRecord(args, context) {
+    return call({ action: "RECORD", workToken: args.workToken, output: args.output }, context);
+}

package/dist/tools/registry.d.ts

@@ -10185,6 +10185,204 @@ export declare const allTools: ({
         };
         required: string[];
     };
+} | {
+    readonly name: "opportunity_sequence_next_page";
+    readonly description: "Read one bounded page of server-selected Lightfield sequence candidates, due work, and exact inbound transitions. Finish a returned continuation before starting a new checkpoint scan.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly continuation: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 8192;
+            };
+            readonly checkpoint: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 8192;
+            };
+            readonly limit: {
+                readonly type: "integer";
+                readonly minimum: 1;
+                readonly maximum: 50;
+            };
+        };
+        readonly required: readonly [];
+        readonly additionalProperties: false;
+    };
+    readonly outputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly ok: {
+                readonly type: "boolean";
+            };
+            readonly error: {
+                readonly type: readonly ["string", "null"];
+            };
+            readonly result: {};
+        };
+        readonly required: readonly ["ok", "error", "result"];
+        readonly additionalProperties: false;
+    };
+    readonly annotations: {
+        readonly title: "Read next Opportunity sequence page";
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+} | {
+    readonly name: "opportunity_sequence_enroll";
+    readonly description: "Idempotently enroll exactly one server-issued Lightfield candidate. The token binds opportunity, contact, trigger, playbook, and source facts; no caller selector is accepted.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly candidateToken: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 8192;
+            };
+        };
+        readonly required: readonly ["candidateToken"];
+        readonly additionalProperties: false;
+    };
+    readonly outputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly ok: {
+                readonly type: "boolean";
+            };
+            readonly error: {
+                readonly type: readonly ["string", "null"];
+            };
+            readonly result: {};
+        };
+        readonly required: readonly ["ok", "error", "result"];
+        readonly additionalProperties: false;
+    };
+    readonly annotations: {
+        readonly title: "Enroll Opportunity sequence candidate";
+        readonly readOnlyHint: false;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+} | {
+    readonly name: "opportunity_sequence_record";
+    readonly description: "Validate one bounded Hermes output against a server-issued work token, reconcile the provider artifact/event identity, append structured Lightfield history first, and then repair the Opportunity projection.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly workToken: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 8192;
+            };
+            readonly output: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly playbook_ref: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly maxLength: 256;
+                    };
+                    readonly playbook_hash: {
+                        readonly type: "string";
+                        readonly pattern: "^[a-f0-9]{64}$";
+                    };
+                    readonly step_id: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly maxLength: 128;
+                    };
+                    readonly source_event_ids: {
+                        readonly type: "array";
+                        readonly minItems: 1;
+                        readonly maxItems: 100;
+                        readonly uniqueItems: true;
+                        readonly items: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                            readonly maxLength: 128;
+                        };
+                    };
+                    readonly source_fingerprint: {
+                        readonly type: "string";
+                        readonly pattern: "^[a-f0-9]{64}$";
+                    };
+                    readonly artifact_type: {
+                        readonly type: "string";
+                        readonly enum: readonly ["email", "linkedin", "call_request", "same_channel_reply"];
+                    };
+                    readonly target: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly contact_id: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                                readonly maxLength: 128;
+                            };
+                            readonly channel: {
+                                readonly type: "string";
+                                readonly enum: readonly ["email", "linkedin", "phone"];
+                            };
+                            readonly address: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                                readonly maxLength: 320;
+                            };
+                        };
+                        readonly required: readonly ["contact_id", "channel"];
+                        readonly additionalProperties: false;
+                    };
+                    readonly due_at: {
+                        readonly type: "string";
+                        readonly format: "date-time";
+                    };
+                    readonly subject: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly maxLength: 200;
+                    };
+                    readonly body: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly maxLength: 4000;
+                    };
+                    readonly rationale_summary: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly maxLength: 600;
+                    };
+                };
+                readonly required: readonly ["playbook_ref", "playbook_hash", "step_id", "source_event_ids", "source_fingerprint", "artifact_type", "target", "due_at", "body", "rationale_summary"];
+                readonly additionalProperties: false;
+            };
+        };
+        readonly required: readonly ["workToken", "output"];
+        readonly additionalProperties: false;
+    };
+    readonly outputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly ok: {
+                readonly type: "boolean";
+            };
+            readonly error: {
+                readonly type: readonly ["string", "null"];
+            };
+            readonly result: {};
+        };
+        readonly required: readonly ["ok", "error", "result"];
+        readonly additionalProperties: false;
+    };
+    readonly annotations: {
+        readonly title: "Record Opportunity sequence work";
+        readonly readOnlyHint: false;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
 } | {
     name: "refill_v3_advance";
     description: string;

package/dist/tools/registry.js

@@ -35,6 +35,7 @@ import { leadToolDefinitions } from "./leads.js";
 import { linkedinToolDefinitions } from "./linkedin.js";
 import { navigationToolDefinitions } from "./navigation.js";
 import { onDemandToolDefinitions } from "./one-off.js";
+import { opportunitySequenceToolDefinitions } from "./opportunity-sequences.js";
 import { processingToolDefinitions } from "./processing.js";
 import { promptToolDefinitions } from "./prompts.js";
 import { findLeadsProviderPreflightToolDefinitions } from "./provider-preflight.js";
@@ -117,6 +118,7 @@ export const allTools = [
     ...promptToolDefinitions,
     ...linkedinToolDefinitions,
     ...onDemandToolDefinitions,
+    ...opportunitySequenceToolDefinitions,
     ...directCampaignToolDefinitions,
     ...companyInfoToolDefinitions,
     ...senderRoutingToolDefinitions,

package/package.json

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