@memberjunction/core-actions 6.1.4 → 6.2.0-edge.1

package/dist/custom/web/perplexity-search.action.d.ts

@@ -1,80 +1,112 @@
 import { ActionResultSimple, RunActionParams } from "@memberjunction/actions-base";
 import { BaseAction } from "@memberjunction/actions";
+/** One result from Perplexity's `/search` endpoint, normalised to this package's naming. */
+export interface PerplexitySearchResultItem {
+    title: string;
+    url: string;
+    snippet: string;
+    /** Publication date when Perplexity resolved one. */
+    date?: string;
+    /** When Perplexity last saw the page change. */
+    lastUpdated?: string;
+}
+/** Which Perplexity product a call routes to. */
+export type PerplexitySearchMode = 'search' | 'answer';
 /**
- * Action that performs AI-powered web search using Perplexity's Search API
- * Returns comprehensive search results with citations and related questions
+ * Action that queries Perplexity. It fronts **two different products**, selected
+ * by `Mode`, because they answer different questions and cost different money.
+ *
+ * - **`search` (default)** calls `POST /search`, Perplexity's raw search endpoint.
+ *   It returns ranked `title` / `url` / `snippet` results with no model in the
+ *   loop: sub-second, flat-priced per query, and deterministic enough to cache.
+ *   This is the mode to use when something wants *sources*.
+ * - **`answer`** calls `POST /chat/completions` against the Sonar models. It
+ *   returns synthesised prose plus a flat citation list, takes seconds rather
+ *   than milliseconds, and bills per token. Use it when a caller genuinely wants
+ *   a written answer rather than results to read.
+ *
+ * `search` is the default deliberately. Every caller that omitted `Mode` before
+ * this parameter existed was paying Sonar generation prices, and waiting for
+ * generation latency, to obtain what was usually just a list of links — and
+ * `Citations` is still populated in `search` mode, so callers that only read the
+ * URL list keep working unchanged.
  *
  * @example
  * ```typescript
- * // Basic search with Perplexity
+ * // Structured results — fast, flat-priced (default)
  * await runAction({
  *   ActionName: 'Perplexity Search',
- *   Params: [{
- *     Name: 'Query',
- *     Value: 'latest developments in quantum computing'
- *   }]
+ *   Params: [{ Name: 'Query', Value: 'latest developments in quantum computing' }]
  * });
  *
- * // Search with specific model and parameters
+ * // Structured results, recent only, restricted to two domains
  * await runAction({
  *   ActionName: 'Perplexity Search',
- *   Params: [{
- *     Name: 'Query',
- *     Value: 'climate change research papers 2024'
- *   }, {
- *     Name: 'Model',
- *     Value: 'sonar-pro'
- *   }, {
- *     Name: 'ReturnRelatedQuestions',
- *     Value: true
- *   }, {
- *     Name: 'ReturnImages',
- *     Value: true
- *   }]
+ *   Params: [
+ *     { Name: 'Query',               Value: 'IRS Form 990 filing changes' },
+ *     { Name: 'MaxResults',          Value: 15 },
+ *     { Name: 'SearchRecencyFilter', Value: 'month' },
+ *     { Name: 'SearchDomainFilter',  Value: ['irs.gov', 'councilofnonprofits.org'] }
+ *   ]
  * });
  *
- * // Search with domain filtering
+ * // A written answer with citations — slower, token-billed
  * await runAction({
  *   ActionName: 'Perplexity Search',
- *   Params: [{
- *     Name: 'Query',
- *     Value: 'machine learning tutorials'
- *   }, {
- *     Name: 'SearchDomainFilter',
- *     Value: ['github.com', 'arxiv.org', 'medium.com']
- *   }]
+ *   Params: [
+ *     { Name: 'Query', Value: 'summarise the 2026 nonprofit reporting changes' },
+ *     { Name: 'Mode',  Value: 'answer' },
+ *     { Name: 'Model', Value: 'sonar-pro' }
+ *   ]
  * });
  * ```
  */
 export declare class PerplexitySearchAction extends BaseAction {
+    private static readonly SEARCH_ENDPOINT;
+    private static readonly CHAT_ENDPOINT;
+    /** Perplexity's cap on results per web-search request. */
+    private static readonly MAX_RESULTS;
+    private static readonly DEFAULT_MAX_RESULTS;
+    /** Perplexity's cap on the domain allow/deny list. */
+    private static readonly MAX_DOMAIN_FILTERS;
+    private static readonly RECENCY_VALUES;
     /**
-     * Executes the Perplexity AI search
+     * Executes the Perplexity call.
      *
      * @param params - The action parameters containing:
      *   - Query: Search query text (required)
-     *   - Model: Perplexity model to use (default: 'sonar')
-     *     Options: sonar, sonar-pro, sonar-reasoning-pro, sonar-deep-research
-     *     Note: the legacy llama-3.1-sonar-* identifiers were retired by Perplexity in
-     *     February 2025 and now fail with an invalid-model error.
-     *   - MaxTokens: Maximum tokens in response (default: 1000)
-     *   - Temperature: Sampling temperature 0-2 (default: 0.2)
-     *   - TopP: Nucleus sampling threshold (default: 0.9)
-     *   - ReturnImages: Include images in results (default: false)
-     *   - ReturnRelatedQuestions: Include related questions (default: false)
-     *   - SearchDomainFilter: Array of domains to limit/exclude search (use '-' prefix to exclude)
-     *   - SearchRecencyFilter: Filter by recency - 'day', 'week', 'month', 'year' (optional)
+     *   - Mode: 'search' (default) for structured results, or 'answer' for Sonar prose
+     *   - SearchDomainFilter: Restrict to these domains (max 20) — both modes
+     *   - SearchRecencyFilter: 'hour' | 'day' | 'week' | 'month' | 'year' — both modes
+     *
+     *   `search` mode only:
+     *   - MaxResults: 1-20 (default 10)
+     *   - Country: 2-letter country code for localisation
+     *
+     *   `answer` mode only:
+     *   - Model: 'sonar' (default), 'sonar-pro', 'sonar-reasoning-pro', 'sonar-deep-research'.
+     *     Note the legacy `llama-3.1-sonar-*` identifiers were retired by Perplexity in
+     *     February 2025 and now fail with an invalid-model error
+     *   - MaxTokens, Temperature, TopP
+     *   - ReturnImages, ReturnRelatedQuestions
      *
-     * @returns Search results with content, citations, and related questions
+     * @returns Structured results in `search` mode; prose plus citations in `answer` mode
      */
     protected InternalRunAction(params: RunActionParams): Promise<ActionResultSimple>;
+    /** `POST /search` — structured results, no model in the loop. */
+    private runSearchMode;
+    /** `POST /chat/completions` — Sonar prose plus citations. */
+    private runAnswerMode;
+    private mapHttpError;
     /**
      * Get string parameter value
      */
     private getStringParam;
     /**
-     * Get parameter value (any type)
+     * A list param, accepted as a real array or as a comma-separated string — both
+     * forms arrive in practice, from agent input mappings and from humans respectively.
      */
-    private getParamValue;
+    private getStringArrayParam;
     /**
      * Get boolean parameter value with default
      */

package/dist/custom/web/perplexity-search.action.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"perplexity-search.action.d.ts","sourceRoot":"","sources":["../../../src/custom/web/perplexity-search.action.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACnF,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAiBrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBACa,sBAAuB,SAAQ,UAAU;IAElD;;;;;;;;;;;;;;;;;;OAkBG;cACa,iBAAiB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA6JvF;;OAEG;IACH,OAAO,CAAC,cAAc;IAMtB;;OAEG;IACH,OAAO,CAAC,aAAa;IAKrB;;OAEG;IACH,OAAO,CAAC,eAAe;IAMvB;;OAEG;IACH,OAAO,CAAC,eAAe;IAOvB;;OAEG;IACH,OAAO,CAAC,cAAc;IAQtB;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAO5B"}
+{"version":3,"file":"perplexity-search.action.d.ts","sourceRoot":"","sources":["../../../src/custom/web/perplexity-search.action.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACnF,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAiBrD,4FAA4F;AAC5F,MAAM,WAAW,0BAA0B;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAgBD,iDAAiD;AACjD,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,qBACa,sBAAuB,SAAQ,UAAU;IAClD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAsC;IAC7E,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAgD;IACrF,0DAA0D;IAC1D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAM;IACzC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAM;IACjD,sDAAsD;IACtD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAM;IAChD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAqD;IAE3F;;;;;;;;;;;;;;;;;;;;;OAqBG;cACa,iBAAiB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAoDvF,iEAAiE;YACnD,aAAa;IA4E3B,6DAA6D;YAC/C,aAAa;IA2E3B,OAAO,CAAC,YAAY;IAoBpB;;OAEG;IACH,OAAO,CAAC,cAAc;IAMtB;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAQ3B;;OAEG;IACH,OAAO,CAAC,eAAe;IAMvB;;OAEG;IACH,OAAO,CAAC,eAAe;IAOvB;;OAEG;IACH,OAAO,CAAC,cAAc;IAQtB;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAO5B"}

package/dist/custom/web/perplexity-search.action.js

@@ -4,195 +4,261 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
+var PerplexitySearchAction_1;
 import { BaseAction } from "@memberjunction/actions";
 import { RegisterClass } from "@memberjunction/global";
 import { HttpPost, IsHttpError } from "@memberjunction/network-utils";
 import { getApiIntegrationsConfig } from "../../config.js";
 /**
- * Action that performs AI-powered web search using Perplexity's Search API
- * Returns comprehensive search results with citations and related questions
+ * Action that queries Perplexity. It fronts **two different products**, selected
+ * by `Mode`, because they answer different questions and cost different money.
+ *
+ * - **`search` (default)** calls `POST /search`, Perplexity's raw search endpoint.
+ *   It returns ranked `title` / `url` / `snippet` results with no model in the
+ *   loop: sub-second, flat-priced per query, and deterministic enough to cache.
+ *   This is the mode to use when something wants *sources*.
+ * - **`answer`** calls `POST /chat/completions` against the Sonar models. It
+ *   returns synthesised prose plus a flat citation list, takes seconds rather
+ *   than milliseconds, and bills per token. Use it when a caller genuinely wants
+ *   a written answer rather than results to read.
+ *
+ * `search` is the default deliberately. Every caller that omitted `Mode` before
+ * this parameter existed was paying Sonar generation prices, and waiting for
+ * generation latency, to obtain what was usually just a list of links — and
+ * `Citations` is still populated in `search` mode, so callers that only read the
+ * URL list keep working unchanged.
  *
  * @example
  * ```typescript
- * // Basic search with Perplexity
+ * // Structured results — fast, flat-priced (default)
  * await runAction({
  *   ActionName: 'Perplexity Search',
- *   Params: [{
- *     Name: 'Query',
- *     Value: 'latest developments in quantum computing'
- *   }]
+ *   Params: [{ Name: 'Query', Value: 'latest developments in quantum computing' }]
  * });
  *
- * // Search with specific model and parameters
+ * // Structured results, recent only, restricted to two domains
  * await runAction({
  *   ActionName: 'Perplexity Search',
- *   Params: [{
- *     Name: 'Query',
- *     Value: 'climate change research papers 2024'
- *   }, {
- *     Name: 'Model',
- *     Value: 'sonar-pro'
- *   }, {
- *     Name: 'ReturnRelatedQuestions',
- *     Value: true
- *   }, {
- *     Name: 'ReturnImages',
- *     Value: true
- *   }]
+ *   Params: [
+ *     { Name: 'Query',               Value: 'IRS Form 990 filing changes' },
+ *     { Name: 'MaxResults',          Value: 15 },
+ *     { Name: 'SearchRecencyFilter', Value: 'month' },
+ *     { Name: 'SearchDomainFilter',  Value: ['irs.gov', 'councilofnonprofits.org'] }
+ *   ]
  * });
  *
- * // Search with domain filtering
+ * // A written answer with citations — slower, token-billed
  * await runAction({
  *   ActionName: 'Perplexity Search',
- *   Params: [{
- *     Name: 'Query',
- *     Value: 'machine learning tutorials'
- *   }, {
- *     Name: 'SearchDomainFilter',
- *     Value: ['github.com', 'arxiv.org', 'medium.com']
- *   }]
+ *   Params: [
+ *     { Name: 'Query', Value: 'summarise the 2026 nonprofit reporting changes' },
+ *     { Name: 'Mode',  Value: 'answer' },
+ *     { Name: 'Model', Value: 'sonar-pro' }
+ *   ]
  * });
  * ```
  */
 let PerplexitySearchAction = class PerplexitySearchAction extends BaseAction {
+    static { PerplexitySearchAction_1 = this; }
+    static { this.SEARCH_ENDPOINT = 'https://api.perplexity.ai/search'; }
+    static { this.CHAT_ENDPOINT = 'https://api.perplexity.ai/chat/completions'; }
+    /** Perplexity's cap on results per web-search request. */
+    static { this.MAX_RESULTS = 20; }
+    static { this.DEFAULT_MAX_RESULTS = 10; }
+    /** Perplexity's cap on the domain allow/deny list. */
+    static { this.MAX_DOMAIN_FILTERS = 20; }
+    static { this.RECENCY_VALUES = ['hour', 'day', 'week', 'month', 'year']; }
     /**
-     * Executes the Perplexity AI search
+     * Executes the Perplexity call.
      *
      * @param params - The action parameters containing:
      *   - Query: Search query text (required)
-     *   - Model: Perplexity model to use (default: 'sonar')
-     *     Options: sonar, sonar-pro, sonar-reasoning-pro, sonar-deep-research
-     *     Note: the legacy llama-3.1-sonar-* identifiers were retired by Perplexity in
-     *     February 2025 and now fail with an invalid-model error.
-     *   - MaxTokens: Maximum tokens in response (default: 1000)
-     *   - Temperature: Sampling temperature 0-2 (default: 0.2)
-     *   - TopP: Nucleus sampling threshold (default: 0.9)
-     *   - ReturnImages: Include images in results (default: false)
-     *   - ReturnRelatedQuestions: Include related questions (default: false)
-     *   - SearchDomainFilter: Array of domains to limit/exclude search (use '-' prefix to exclude)
-     *   - SearchRecencyFilter: Filter by recency - 'day', 'week', 'month', 'year' (optional)
+     *   - Mode: 'search' (default) for structured results, or 'answer' for Sonar prose
+     *   - SearchDomainFilter: Restrict to these domains (max 20) — both modes
+     *   - SearchRecencyFilter: 'hour' | 'day' | 'week' | 'month' | 'year' — both modes
+     *
+     *   `search` mode only:
+     *   - MaxResults: 1-20 (default 10)
+     *   - Country: 2-letter country code for localisation
      *
-     * @returns Search results with content, citations, and related questions
+     *   `answer` mode only:
+     *   - Model: 'sonar' (default), 'sonar-pro', 'sonar-reasoning-pro', 'sonar-deep-research'.
+     *     Note the legacy `llama-3.1-sonar-*` identifiers were retired by Perplexity in
+     *     February 2025 and now fail with an invalid-model error
+     *   - MaxTokens, Temperature, TopP
+     *   - ReturnImages, ReturnRelatedQuestions
+     *
+     * @returns Structured results in `search` mode; prose plus citations in `answer` mode
      */
     async InternalRunAction(params) {
+        const query = this.getStringParam(params, 'query');
+        if (!query) {
+            return this.createErrorResult("Query parameter is required", "MISSING_QUERY");
+        }
+        const mode = (this.getStringParam(params, 'mode') || 'search').trim().toLowerCase();
+        if (mode !== 'search' && mode !== 'answer') {
+            return this.createErrorResult(`Mode must be 'search' or 'answer' (got '${mode}')`, "INVALID_MODE");
+        }
+        const apiKey = getApiIntegrationsConfig().perplexityApiKey;
+        if (!apiKey) {
+            return this.createErrorResult("Perplexity API key not found. Set perplexityApiKey in mj.config.cjs or PERPLEXITY_API_KEY environment variable", "MISSING_API_KEY");
+        }
+        const recency = this.getStringParam(params, 'searchrecencyfilter')?.trim().toLowerCase();
+        if (recency && !PerplexitySearchAction_1.RECENCY_VALUES.includes(recency)) {
+            return this.createErrorResult(`SearchRecencyFilter must be one of ${PerplexitySearchAction_1.RECENCY_VALUES.join(', ')} (got '${recency}')`, "INVALID_RECENCY_FILTER");
+        }
+        // Truncated rather than rejected: Perplexity 400s on an over-long list, and the
+        // first 20 domains still express what the caller was narrowing to.
+        const domainFilter = this.getStringArrayParam(params, 'searchdomainfilter')
+            .slice(0, PerplexitySearchAction_1.MAX_DOMAIN_FILTERS);
         try {
-            // Get required parameters
-            const query = this.getStringParam(params, 'query');
-            if (!query) {
-                return this.createErrorResult("Query parameter is required", "MISSING_QUERY");
-            }
-            // Get API key from config (which checks mj.config.cjs then falls back to environment variable)
-            const apiConfig = getApiIntegrationsConfig();
-            const apiKey = apiConfig.perplexityApiKey;
-            if (!apiKey) {
-                return this.createErrorResult("Perplexity API key not found. Set perplexityApiKey in mj.config.cjs or PERPLEXITY_API_KEY environment variable", "MISSING_API_KEY");
-            }
-            // Get optional parameters
-            const model = this.getStringParam(params, 'model') || 'sonar';
-            const maxTokens = this.getNumericParam(params, 'maxtokens', 1000);
-            const temperature = this.getNumericParam(params, 'temperature', 0.2);
-            const topP = this.getNumericParam(params, 'topp', 0.9);
-            const returnImages = this.getBooleanParam(params, 'returnimages', false);
-            const returnRelatedQuestions = this.getBooleanParam(params, 'returnrelatedquestions', false);
-            const searchRecencyFilter = this.getStringParam(params, 'searchrecencyfilter');
-            // Get domain filter (can be array or comma-separated string)
-            const domainFilterParam = this.getParamValue(params, 'searchdomainfilter');
-            let searchDomainFilter;
-            if (domainFilterParam) {
-                if (Array.isArray(domainFilterParam)) {
-                    searchDomainFilter = domainFilterParam;
-                }
-                else if (typeof domainFilterParam === 'string') {
-                    searchDomainFilter = domainFilterParam.split(',').map(d => d.trim());
-                }
-            }
-            // Build request body
-            const requestBody = {
-                model,
-                messages: [
-                    {
-                        role: 'user',
-                        content: query
-                    }
-                ],
-                max_tokens: maxTokens,
-                temperature,
-                top_p: topP,
-                return_images: returnImages,
-                return_related_questions: returnRelatedQuestions,
-                stream: false
-            };
-            // Add optional parameters
-            if (searchDomainFilter && searchDomainFilter.length > 0) {
-                requestBody.search_domain_filter = searchDomainFilter;
-            }
-            if (searchRecencyFilter) {
-                requestBody.search_recency_filter = searchRecencyFilter;
-            }
-            // Make API request
-            const response = await HttpPost('https://api.perplexity.ai/chat/completions', requestBody, {
-                Headers: {
-                    'Authorization': `Bearer ${apiKey}`,
-                    'Content-Type': 'application/json'
-                },
-                Timeout: 60000 // 60 second timeout
-            });
-            if (!response.Data) {
-                return this.createErrorResult("Empty response from Perplexity API", "EMPTY_RESPONSE");
+            return mode === 'search'
+                ? await this.runSearchMode(params, { query, apiKey, recency, domainFilter })
+                : await this.runAnswerMode(params, { query, apiKey, recency, domainFilter });
+        }
+        catch (error) {
+            // Status 0 is HttpError's "the request never produced a response" — a timeout or a
+            // network failure. That is not an API answer, so it falls through to SEARCH_FAILED.
+            if (IsHttpError(error) && error.Status > 0) {
+                return this.mapHttpError(error);
             }
-            // Extract response data
-            const result = response.Data;
-            const choice = result.choices?.[0];
-            const message = choice?.message;
-            const content = message?.content || '';
-            const citations = result.citations || [];
-            const images = result.images || [];
-            const relatedQuestions = result.related_questions || [];
-            // Build output data
-            const outputData = {
-                query,
-                model,
-                content,
-                citations,
-                images,
-                relatedQuestions,
-                usage: result.usage || {},
-                finishReason: choice?.finish_reason
+            return this.createErrorResult(`Failed to perform Perplexity search: ${error instanceof Error ? error.message : String(error)}`, "SEARCH_FAILED");
+        }
+    }
+    /** `POST /search` — structured results, no model in the loop. */
+    async runSearchMode(params, ctx) {
+        // Clamped rather than rejected, matching Tavily and Brave: a caller asking for
+        // 50 wants as many as possible, and Perplexity rejects the whole request above its cap.
+        const maxResults = Math.min(Math.max(Math.floor(this.getNumericParam(params, 'maxresults', PerplexitySearchAction_1.DEFAULT_MAX_RESULTS)), 1), PerplexitySearchAction_1.MAX_RESULTS);
+        const requestBody = { query: ctx.query, max_results: maxResults };
+        if (ctx.domainFilter.length > 0) {
+            requestBody.search_domain_filter = ctx.domainFilter;
+        }
+        if (ctx.recency) {
+            requestBody.search_recency_filter = ctx.recency;
+        }
+        const country = this.getStringParam(params, 'country');
+        if (country) {
+            requestBody.country = country.trim().toUpperCase();
+        }
+        const response = await HttpPost(PerplexitySearchAction_1.SEARCH_ENDPOINT, requestBody, { Headers: { 'Authorization': `Bearer ${ctx.apiKey}` }, Timeout: 30000 });
+        if (!response.Data) {
+            return this.createErrorResult("Empty response from Perplexity Search API", "EMPTY_RESPONSE");
+        }
+        const results = (response.Data.results ?? []).map((item) => {
+            const mapped = {
+                title: item.title ?? '',
+                url: item.url ?? '',
+                snippet: item.snippet ?? '',
             };
-            // Add output parameters
-            this.addOutputParam(params, 'Content', content);
-            this.addOutputParam(params, 'Citations', citations);
-            this.addOutputParam(params, 'CitationCount', citations.length);
-            if (returnImages && images.length > 0) {
-                this.addOutputParam(params, 'Images', images);
-                this.addOutputParam(params, 'ImageCount', images.length);
+            if (item.date) {
+                mapped.date = item.date;
             }
-            if (returnRelatedQuestions && relatedQuestions.length > 0) {
-                this.addOutputParam(params, 'RelatedQuestions', relatedQuestions);
-                this.addOutputParam(params, 'RelatedQuestionCount', relatedQuestions.length);
+            if (item.last_updated) {
+                mapped.lastUpdated = item.last_updated;
             }
-            this.addOutputParam(params, 'Usage', result.usage);
-            this.addOutputParam(params, 'SearchResultDetails', outputData);
-            return {
-                Success: true,
-                ResultCode: "SUCCESS",
-                Message: JSON.stringify(outputData, null, 2)
-            };
+            return mapped;
+        });
+        // `Citations` is emitted here too, holding the result URLs. Callers written against
+        // the old answer-only behaviour read that param, and this keeps them working when
+        // the default mode changed underneath them.
+        const citations = results.map(r => r.url).filter(u => u.length > 0);
+        this.addOutputParam(params, 'Results', results);
+        this.addOutputParam(params, 'ResultCount', results.length);
+        this.addOutputParam(params, 'Citations', citations);
+        this.addOutputParam(params, 'CitationCount', citations.length);
+        this.addOutputParam(params, 'SearchResultDetails', {
+            query: ctx.query,
+            mode: 'search',
+            maxResults,
+            results,
+            citations,
+            serverTime: response.Data.server_time,
+        });
+        // Zero results is a real answer to a narrow query, not a failure.
+        return {
+            Success: true,
+            ResultCode: "SUCCESS",
+            Message: results.length === 0
+                ? `Perplexity returned no results for '${ctx.query}'.`
+                : `Perplexity returned ${results.length} result(s) for '${ctx.query}'.`
+        };
+    }
+    /** `POST /chat/completions` — Sonar prose plus citations. */
+    async runAnswerMode(params, ctx) {
+        const model = this.getStringParam(params, 'model') || 'sonar';
+        const returnImages = this.getBooleanParam(params, 'returnimages', false);
+        const returnRelatedQuestions = this.getBooleanParam(params, 'returnrelatedquestions', false);
+        const requestBody = {
+            model,
+            messages: [{ role: 'user', content: ctx.query }],
+            max_tokens: this.getNumericParam(params, 'maxtokens', 1000),
+            temperature: this.getNumericParam(params, 'temperature', 0.2),
+            top_p: this.getNumericParam(params, 'topp', 0.9),
+            return_images: returnImages,
+            return_related_questions: returnRelatedQuestions,
+            stream: false
+        };
+        if (ctx.domainFilter.length > 0) {
+            requestBody.search_domain_filter = ctx.domainFilter;
         }
-        catch (error) {
-            if (IsHttpError(error)) {
-                const status = error.Status;
-                const errorData = error.Data;
-                if (status === 401) {
-                    return this.createErrorResult("Invalid Perplexity API key", "INVALID_API_KEY");
-                }
-                if (status === 429) {
-                    return this.createErrorResult("Perplexity API rate limit exceeded", "RATE_LIMITED");
-                }
-                return this.createErrorResult(`Perplexity API error: ${errorData?.error?.message || error.message}`, "API_ERROR");
-            }
-            return this.createErrorResult(`Failed to perform Perplexity search: ${error instanceof Error ? error.message : String(error)}`, "SEARCH_FAILED");
+        if (ctx.recency) {
+            requestBody.search_recency_filter = ctx.recency;
+        }
+        const response = await HttpPost(PerplexitySearchAction_1.CHAT_ENDPOINT, requestBody, { Headers: { 'Authorization': `Bearer ${ctx.apiKey}` }, Timeout: 60000 });
+        if (!response.Data) {
+            return this.createErrorResult("Empty response from Perplexity API", "EMPTY_RESPONSE");
+        }
+        const result = response.Data;
+        const choice = result.choices?.[0];
+        const content = choice?.message?.content || '';
+        const citations = result.citations || [];
+        const images = result.images || [];
+        const relatedQuestions = result.related_questions || [];
+        const outputData = {
+            query: ctx.query,
+            mode: 'answer',
+            model,
+            content,
+            citations,
+            images,
+            relatedQuestions,
+            usage: result.usage || {},
+            finishReason: choice?.finish_reason
+        };
+        this.addOutputParam(params, 'Content', content);
+        this.addOutputParam(params, 'Citations', citations);
+        this.addOutputParam(params, 'CitationCount', citations.length);
+        if (returnImages && images.length > 0) {
+            this.addOutputParam(params, 'Images', images);
+            this.addOutputParam(params, 'ImageCount', images.length);
+        }
+        if (returnRelatedQuestions && relatedQuestions.length > 0) {
+            this.addOutputParam(params, 'RelatedQuestions', relatedQuestions);
+            this.addOutputParam(params, 'RelatedQuestionCount', relatedQuestions.length);
+        }
+        this.addOutputParam(params, 'Usage', result.usage);
+        this.addOutputParam(params, 'SearchResultDetails', outputData);
+        return {
+            Success: true,
+            ResultCode: "SUCCESS",
+            Message: JSON.stringify(outputData, null, 2)
+        };
+    }
+    mapHttpError(error) {
+        const status = error.Status;
+        const errorData = error.Data;
+        const detail = errorData?.error?.message || error.message;
+        if (status === 401 || status === 403) {
+            return this.createErrorResult(`Invalid Perplexity API key (HTTP ${status})`, "INVALID_API_KEY");
+        }
+        if (status === 429) {
+            return this.createErrorResult("Perplexity API rate limit exceeded", "RATE_LIMITED");
+        }
+        if (status === 400 || status === 422) {
+            return this.createErrorResult(`Perplexity rejected the request (HTTP ${status}): ${detail}`, "INVALID_REQUEST");
         }
+        return this.createErrorResult(`Perplexity API error: ${detail}`, "API_ERROR");
     }
     /**
      * Get string parameter value
@@ -204,11 +270,16 @@ let PerplexitySearchAction = class PerplexitySearchAction extends BaseAction {
         return String(param.Value);
     }
     /**
-     * Get parameter value (any type)
+     * A list param, accepted as a real array or as a comma-separated string — both
+     * forms arrive in practice, from agent input mappings and from humans respectively.
      */
-    getParamValue(params, paramName) {
+    getStringArrayParam(params, paramName) {
         const param = params.Params.find(p => p.Name.trim().toLowerCase() === paramName.toLowerCase());
-        return param?.Value;
+        const value = param?.Value;
+        if (value === undefined || value === null)
+            return [];
+        const raw = Array.isArray(value) ? value.map(v => String(v)) : String(value).split(',');
+        return raw.map(v => v.trim()).filter(v => v.length > 0);
     }
     /**
      * Get boolean parameter value with default
@@ -250,7 +321,7 @@ let PerplexitySearchAction = class PerplexitySearchAction extends BaseAction {
         };
     }
 };
-PerplexitySearchAction = __decorate([
+PerplexitySearchAction = PerplexitySearchAction_1 = __decorate([
     RegisterClass(BaseAction, "Perplexity Search")
 ], PerplexitySearchAction);
 export { PerplexitySearchAction };