Working hours

Author: KirillSergeevich

package-lock.json

@@ -30,7 +30,7 @@
   "author": "Linked API",
   "license": "MIT",
   "dependencies": {
-    "@linkedapi/node": "^2.3.5",
+    "@linkedapi/node": "^2.3.6",
     "@modelcontextprotocol/sdk": "^1.17.4",
     "zod": "^4.1.1"
   },

package.json

@@ -8,7 +8,9 @@ import { logger } from './utils/logger';
 import { CallToolResult, ExtendedCallToolRequest } from './utils/types';
 
 const BACKGROUND_WORKFLOW_DESCRIPTION =
-  `Linked API actions are queued into a cloud-browser workflow and may take several minutes. The server returns immediately after starting the workflow with {status: 'pending'|'running', workflowId, operationName, message}. To retrieve the final result, call get_workflow_result with the returned workflowId and operationName — it will long-poll until completion or the request budget elapses, then return either the final result or another in-progress snapshot. Do not retry the original tool while a workflow is still running; that creates duplicate queued work.` as const;
+  `Linked API actions are queued into a cloud-browser workflow and may take several minutes. The server returns immediately after starting the workflow with {status: 'pending'|'running', pendingReason, workflowId, operationName, message}. To retrieve the final result, call get_workflow_result with the returned workflowId and operationName — it will long-poll until completion or the request budget elapses, then return either the final result or another in-progress snapshot. Do not retry the original tool while a workflow is still running; that creates duplicate queued work.
+
+A pending workflow carries pendingReason: 'queued' means it is waiting its turn behind other work on the same account and will start within minutes. 'outsideWorkingHours' means the account has configured working hours and the workflow is parked until they reopen — possibly the next working day. In that case get_workflow_result returns immediately instead of polling, message states when the window opens, and you should report that to the user rather than looping.` as const;
 const NON_WORKFLOW_TOOL_NAMES = new Set<string>(['get_workflow_result', 'get_api_usage'] as const);
 
 interface TExecuteWithTokensOptions extends TLinkedApiConfig {
@@ -105,6 +107,9 @@ export class LinkedApiMCPServer {
       if ('workflowStatus' in result) {
         const inProgressBody = {
           status: result.workflowStatus,
+          // Surfaced so the caller can tell "waiting its turn, minutes" from "parked until the
+          // account working hours reopen", which can be the next working day.
+          pendingReason: result.pendingReason ?? null,
           workflowId: result.workflowId,
           operationName: result.operationName,
           message: result.message,

src/linked-api-server.ts

@@ -33,11 +33,31 @@ LINKEDIN WORKFLOWS RUN IN THE BACKGROUND:
 - Simply continue listening for updates using get_workflow_result
 
 WHEN A WORKFLOW IS RUNNING IN BACKGROUND:
-1. You'll receive a status message with: workflowId, status, message, and operationName
+1. You'll receive a status message with: workflowId, status, pendingReason, message, and operationName
 2. Use get_workflow_result(workflowId, operationName) to continue listening for updates
 3. Keep listening until you get the final results
 4. This is normal workflow operation - the task is actively running
 
+WHEN A WORKFLOW IS PARKED OUTSIDE WORKING HOURS:
+- pendingReason is "outsideWorkingHours": the account has configured working hours and this
+  workflow will not start until they reopen, which may be the next working day
+- get_workflow_result returns immediately in this case instead of polling
+- Do NOT keep calling get_workflow_result in a loop and do NOT restart the workflow
+- Tell the user when the window opens (the message says so) and that the work will start by itself
+
+EXAMPLE PARKED WORKFLOW MESSAGE:
+{
+  "status": "pending",
+  "pendingReason": "outsideWorkingHours",
+  "message": "This workflow is scheduled and will start when the account working hours open at Mon, Aug 10, 09:00 (Europe/Berlin).",
+  "workflowId": "account-12345-abcde",
+  "operationName": "searchCompanies"
+}
+
+RESPONSE: "This account is outside its working hours right now, so the search is queued and will
+start automatically on Monday at 09:00 (Europe/Berlin). Nothing else is needed from you."
+
+
 EXAMPLE BACKGROUND WORKFLOW MESSAGE:
 {
   "message": "Workflow is running in the background. Continue listening for updates.",

src/prompts/index.ts

@@ -1,4 +1,5 @@
 import LinkedApi, {
+  LINKED_API_WORKFLOW_PENDING_REASON,
   Operation,
   OPERATION_NAME,
   TMappedResponse,
@@ -55,6 +56,11 @@ export class GetWorkflowResultTool extends LinkedApiTool<IGetWorkflowResultParam
       if (!isWorkflowInProgress(status)) {
         return status;
       }
+      if (status.pendingReason === LINKED_API_WORKFLOW_PENDING_REASON.outsideWorkingHours) {
+        return { ...status,
+workflowId,
+operationName: typedOperationName };
+      }
       const remainingMs = deadline - Date.now();
       if (remainingMs <= 0) {
         return { ...status,
@@ -69,7 +75,7 @@ operationName: typedOperationName };
     return {
       name: this.name,
       description:
-        'Check the current state of a previously started Linked API workflow. Returns the final result when the workflow has completed, otherwise returns the current in-progress snapshot ({status, workflowId, operationName, message}). The server long-polls up to waitSeconds while the workflow is still running; if the budget elapses without completion, the in-progress snapshot is returned and the client should call this tool again with the same workflowId and operationName.',
+        'Check the current state of a previously started Linked API workflow. Returns the final result when the workflow has completed, otherwise returns the current in-progress snapshot ({status, pendingReason, workflowId, operationName, message}). The server long-polls up to waitSeconds while the workflow is still running; if the budget elapses without completion, the in-progress snapshot is returned and the client should call this tool again with the same workflowId and operationName. Exception: when pendingReason is "outsideWorkingHours" the workflow is parked until the account working hours reopen — the server returns immediately without polling, message states when that is, and calling this tool again before then will report the same state.',
       inputSchema: {
         type: 'object',
         properties: {

src/tools/get-workflow-result.ts

@@ -17,6 +17,18 @@ export function handleLinkedApiError(error: LinkedApiError): Record<string, unkn
         type: error.type,
         retryable: false,
       };
+    case 'outsideWorkingHours':
+      return {
+        message: `${error.message} Retry once the account working hours reopen, or ask the account owner to change the off-hours policy.`,
+        type: error.type,
+        retryable: false,
+      };
+    case 'workingHoursWaitExpired':
+      return {
+        message: `${error.message} Start it again inside the account working hours.`,
+        type: error.type,
+        retryable: false,
+      };
   }
   return {
     message: error.message,