Class TaskExecutor

Core task execution engine that handles the conversation loop with agents

Index

Constructors

Methods

getGovernanceMiddleware validateRequest validateAdaptedRequestAgainstV2 executeTask listTasks getTaskStatus pollTaskCompletion resumeDeferredTask getConversationHistory clearConversationHistory getActiveTasks getTaskList getTaskInfo onTaskUpdate onTaskEvents registerWebhook unregisterWebhook

Constructors

constructor

new TaskExecutor(
    config?: {
        workingTimeout?: number;
        pollingInterval?: number;
        defaultMaxClarifications?: number;
        enableConversationStorage?: boolean;
        webhookManager?: WebhookManager;
        deferredStorage?: Storage<DeferredTaskState>;
        webhookUrlTemplate?: string;
        agentId?: string;
        webhookSecret?: string;
        strictSchemaValidation?: boolean;
        logSchemaViolations?: boolean;
        validation?: ValidationHookConfig;
        filterInvalidProducts?: boolean;
        onActivity?: (activity: Activity) => void | Promise<void>;
        governance?: GovernanceConfig;
        adcpVersion?: string;
        transport?: TransportOptions;
    },
): TaskExecutor
Parameters
- config: {
      workingTimeout?: number;
      pollingInterval?: number;
      defaultMaxClarifications?: number;
      enableConversationStorage?: boolean;
      webhookManager?: WebhookManager;
      deferredStorage?: Storage<DeferredTaskState>;
      webhookUrlTemplate?: string;
      agentId?: string;
      webhookSecret?: string;
      strictSchemaValidation?: boolean;
      logSchemaViolations?: boolean;
      validation?: ValidationHookConfig;
      filterInvalidProducts?: boolean;
      onActivity?: (activity: Activity) => void | Promise<void>;
      governance?: GovernanceConfig;
      adcpVersion?: string;
      transport?: TransportOptions;
  } = {}
  - OptionalworkingTimeout?: number
    Default timeout for 'working' status (max 120s per PR #78)
  - OptionalpollingInterval?: number
    Polling interval for 'working' status in milliseconds (default: 2000ms)
  - OptionaldefaultMaxClarifications?: number
    Default max clarification attempts
  - OptionalenableConversationStorage?: boolean
    Enable conversation storage
  - OptionalwebhookManager?: WebhookManager
    Webhook manager for submitted tasks
  - OptionaldeferredStorage?: Storage<DeferredTaskState>
    Storage for deferred task state
  - OptionalwebhookUrlTemplate?: string
    Webhook URL template for protocol-level webhook support
  - OptionalagentId?: string
    Agent ID for webhook URL generation
  - OptionalwebhookSecret?: string
    Webhook secret for HMAC authentication (min 32 chars)
  - OptionalstrictSchemaValidation?: boolean
    Fail tasks when response schema validation fails (default: true)
  - OptionallogSchemaViolations?: boolean
    Log all schema validation violations to debug logs (default: true)
  - Optionalvalidation?: ValidationHookConfig
    Schema-driven validation using the bundled AdCP JSON schemas. Controls outgoing request and incoming response checks independently. Defaults: strict in dev/test, warn in prod. Set a mode to off to skip the validator entirely on that side (zero overhead).
  - OptionalfilterInvalidProducts?: boolean
    Filter out invalid products from get_products responses instead of rejecting the entire response (default: false)
  - OptionalonActivity?: (activity: Activity) => void | Promise<void>
    Global activity callback for observability
  - Optionalgovernance?: GovernanceConfig
    Governance configuration for buyer-side campaign governance
  - OptionaladcpVersion?: string
    AdCP version this executor speaks. Selects which schema bundle validateIncomingResponse / validateOutgoingRequest validate against, and which adcp_major_version value goes on the wire. Defaults to the SDK-pinned ADCP_VERSION when omitted.
    
    Plumbed from SingleAgentClient.resolvedAdcpVersion so the client/agent's getAdcpVersion() value is the single source of truth for both validation and wire-level major.
  - Optionaltransport?: TransportOptions
    Transport-level safeguards applied to every call this executor dispatches. Per-call options can override individual fields.
Returns TaskExecutor
- Defined in src/lib/core/TaskExecutor.ts:274

Methods

getGovernanceMiddleware

getGovernanceMiddleware(): GovernanceMiddleware | undefined
Access the governance middleware for direct outcome reporting (async tasks).

Returns GovernanceMiddleware | undefined
- Defined in src/lib/core/TaskExecutor.ts:353

validateRequest

validateRequest(taskName: string, params: unknown, debugLogs?: any[]): void
Run the configured pre-send schema check against the user-facing request shape. Callers invoke this on the unadapted (v3) params before any wire adaptation runs, so the validator sees the same object the caller wrote. Throws in strict, logs to debugLogs in warn, no-ops in off.
Parameters
- taskName: string
- params: unknown
- OptionaldebugLogs: any[]
Returns void
- Defined in src/lib/core/TaskExecutor.ts:363

validateAdaptedRequestAgainstV2

validateAdaptedRequestAgainstV2(
    taskName: string,
    adaptedParams: unknown,
    debugLogs?: any[],
): void
After adaptRequestForServerVersion has rewritten a v3 request into v2 wire format, validate the adapted shape against the cached v2.5 schema bundle. Always warn-only — adapter bugs shouldn't break user requests, and the v3 pre-send pass already vouched for the user-facing input. This pass exists to surface drift between what the adapter emits and what a v2.5 server expects on the wire (primarily as CI signal via the adapter-conformance test suite).

Skips silently for tasks without a v2.5 schema or when the v2.5 bundle isn't cached. Caller is responsible for gating on serverVersion === 'v2' so v3-targeted traffic doesn't pay the validation cost.
Parameters
- taskName: string
- adaptedParams: unknown
- OptionaldebugLogs: any[]
Returns void
- Defined in src/lib/core/TaskExecutor.ts:380

executeTask

executeTask<T = any>(
    agent: AgentConfig,
    taskName: string,
    params: any,
    inputHandler?: InputHandler,
    options?: TaskOptions,
    serverVersion?: "v2" | "v3",
): Promise<TaskResult<T>>
Execute a task with an agent using PR #78 async patterns Handles: working (keep SSE open), submitted (webhook), input-required (handler), completed
Type Parameters
- T = any
Parameters
- agent: AgentConfig
- taskName: string
- params: any
- OptionalinputHandler: InputHandler
- options: TaskOptions = {}
- OptionalserverVersion: "v2" | "v3"
Returns Promise<TaskResult<T>>
- Defined in src/lib/core/TaskExecutor.ts:458

listTasks

listTasks(agent: AgentConfig, transport?: TransportOptions): Promise<TaskInfo[]>
Task tracking methods (PR #78)
Parameters
- agent: AgentConfig
- Optionaltransport: TransportOptions
Returns Promise<TaskInfo[]>
- Defined in src/lib/core/TaskExecutor.ts:1345

getTaskStatus

getTaskStatus(
    agent: AgentConfig,
    taskId: string,
    transport?: TransportOptions,
): Promise<TaskInfo>
Parameters
- agent: AgentConfig
- taskId: string
- Optionaltransport: TransportOptions
Returns Promise<TaskInfo>
- Defined in src/lib/core/TaskExecutor.ts:1358

pollTaskCompletion

pollTaskCompletion<T>(
    agent: AgentConfig,
    taskId: string,
    pollInterval?: number,
    transport?: TransportOptions,
    signal?: AbortSignal,
): Promise<TaskResult<T>>
Type Parameters
- T
Parameters
- agent: AgentConfig
- taskId: string
- pollInterval: number = 60000
- Optionaltransport: TransportOptions
- Optionalsignal: AbortSignal
Returns Promise<TaskResult<T>>
- Defined in src/lib/core/TaskExecutor.ts:1412

resumeDeferredTask

resumeDeferredTask<T>(token: string, input: any): Promise<TaskResult<T>>
Resume a deferred task (client deferral)
Type Parameters
- T
Parameters
- token: string
- input: any
Returns Promise<TaskResult<T>>
- Defined in src/lib/core/TaskExecutor.ts:1624

getConversationHistory

getConversationHistory(taskId: string): Message[] | undefined
Legacy methods for backward compatibility
Parameters
- taskId: string
Returns Message[] | undefined
- Defined in src/lib/core/TaskExecutor.ts:1756

clearConversationHistory

clearConversationHistory(taskId: string): void
Parameters
- taskId: string
Returns void
- Defined in src/lib/core/TaskExecutor.ts:1760

getActiveTasks

getActiveTasks(): TaskState[]
Returns TaskState[]
- Defined in src/lib/core/TaskExecutor.ts:1764

getTaskList

getTaskList(agentId: string, transport?: TransportOptions): Promise<TaskInfo[]>
Get task list for a specific agent
Parameters
- agentId: string
- Optionaltransport: TransportOptions
Returns Promise<TaskInfo[]>
- Defined in src/lib/core/TaskExecutor.ts:1790

getTaskInfo

getTaskInfo(taskId: string): Promise<TaskInfo | null>
Get detailed information about a specific task
Parameters
- taskId: string
Returns Promise<TaskInfo | null>
- Defined in src/lib/core/TaskExecutor.ts:1817

onTaskUpdate

onTaskUpdate(agentId: string, callback: (task: TaskInfo) => void): () => void
Subscribe to task updates for a specific agent
Parameters
- agentId: string
- callback: (task: TaskInfo) => void
Returns () => void
- Defined in src/lib/core/TaskExecutor.ts:1837

onTaskEvents

onTaskEvents(
    agentId: string,
    callbacks: {
        onTaskCreated?: (task: TaskInfo) => void;
        onTaskUpdated?: (task: TaskInfo) => void;
        onTaskCompleted?: (task: TaskInfo) => void;
        onTaskFailed?: (task: TaskInfo, error: string) => void;
    },
): () => void
Subscribe to task events with detailed callbacks
Parameters
- agentId: string
- callbacks: {
      onTaskCreated?: (task: TaskInfo) => void;
      onTaskUpdated?: (task: TaskInfo) => void;
      onTaskCompleted?: (task: TaskInfo) => void;
      onTaskFailed?: (task: TaskInfo, error: string) => void;
  }
Returns () => void
- Defined in src/lib/core/TaskExecutor.ts:1851

registerWebhook

registerWebhook(
    agent: AgentConfig,
    webhookUrl: string,
    taskTypes?: string[],
): Promise<void>
Register webhook for task notifications
Parameters
- agent: AgentConfig
- webhookUrl: string
- OptionaltaskTypes: string[]
Returns Promise<void>
- Defined in src/lib/core/TaskExecutor.ts:1895

unregisterWebhook

unregisterWebhook(agent: AgentConfig): Promise<void>
Unregister webhook notifications
Parameters
- agent: AgentConfig
Returns Promise<void>
- Defined in src/lib/core/TaskExecutor.ts:1909

Class TaskExecutor

Index

Constructors

Methods

Constructors

constructor

Parameters

OptionalworkingTimeout?: number

OptionalpollingInterval?: number

OptionaldefaultMaxClarifications?: number

OptionalenableConversationStorage?: boolean

OptionalwebhookManager?: WebhookManager

OptionaldeferredStorage?: Storage<DeferredTaskState>

OptionalwebhookUrlTemplate?: string

OptionalagentId?: string

OptionalwebhookSecret?: string

OptionalstrictSchemaValidation?: boolean

OptionallogSchemaViolations?: boolean

Optionalvalidation?: ValidationHookConfig

OptionalfilterInvalidProducts?: boolean

OptionalonActivity?: (activity: Activity) => void | Promise<void>

Optionalgovernance?: GovernanceConfig

OptionaladcpVersion?: string

Optionaltransport?: TransportOptions

Returns TaskExecutor

Methods

getGovernanceMiddleware

Returns GovernanceMiddleware | undefined

validateRequest

Parameters

Returns void

validateAdaptedRequestAgainstV2

Parameters

Returns void

executeTask

Type Parameters

Parameters

Returns Promise<TaskResult<T>>

listTasks

Parameters

Returns Promise<TaskInfo[]>

getTaskStatus

Parameters

Returns Promise<TaskInfo>

pollTaskCompletion

Type Parameters

Parameters

Returns Promise<TaskResult<T>>

resumeDeferredTask

Type Parameters

Parameters

Returns Promise<TaskResult<T>>

getConversationHistory

Parameters

Returns Message[] | undefined

clearConversationHistory

Parameters

Returns void

getActiveTasks

Returns TaskState[]

getTaskList

Parameters

Returns Promise<TaskInfo[]>

getTaskInfo

Parameters

Returns Promise<TaskInfo | null>

onTaskUpdate

Parameters

Returns () => void

onTaskEvents

Parameters

Returns () => void

registerWebhook

Parameters

Returns Promise<void>

unregisterWebhook

Parameters

Returns Promise<void>

Settings

On This Page

`Optional`workingTimeout?: number

`Optional`pollingInterval?: number

`Optional`defaultMaxClarifications?: number

`Optional`enableConversationStorage?: boolean

`Optional`webhookManager?: WebhookManager

`Optional`deferredStorage?: Storage<DeferredTaskState>

`Optional`webhookUrlTemplate?: string

`Optional`agentId?: string

`Optional`webhookSecret?: string

`Optional`strictSchemaValidation?: boolean

`Optional`logSchemaViolations?: boolean

`Optional`validation?: ValidationHookConfig

`Optional`filterInvalidProducts?: boolean

`Optional`onActivity?: (activity: Activity) => void | Promise<void>

`Optional`governance?: GovernanceConfig

`Optional`adcpVersion?: string

`Optional`transport?: TransportOptions