Poller worker

Configure a POLLER_WORKER for hosted poller ingress: provider, auth.secretRef, Linear provider fields, and POLLER_RUN companionship distinct from workstation behavior POLLER.

How To Use

Author a worker with type POLLER_WORKER. Set provider to a built-in hosted identity such as LINEAR. Authenticate through auth.secretRef only. Add optional linear fields such as pollInterval, teamIds, stateIds, mapping, and claim when the Linear poller needs them. Bind the worker from a POLLER_RUN workstation companion, and keep behavior POLLER with outputs and onFailure on the workstation that owns ingress scheduling. Do not treat POLLER_RUN and behavior POLLER as the same contract. Poller workers are not model-backed backends: they do not own model, modelProvider, modelLocality, operations, command, args, or agentTools.

Discriminator: type = POLLER_WORKER

POLLER_WORKER pairs with a POLLER_RUN workstation type companion. Workstation behavior POLLER is a separate scheduling axis for long-lived ingress—do not treat type and behavior as interchangeable.

Schema reference

The embed below shows the live Worker base definition with POLLER_WORKER overlay applicability. Selected fields are hosted-poller exclusive (provider, auth, linear). Excluded fields belong to other WorkerType families and must not appear on this variant. Open the full Factory schema reference for exhaustive field lookup rather than copying contract text into this page.

Worker

object

A reusable worker definition that tells the factory how a workstation should execute work, such as through a model-backed agent or a script.

additionalPropertiesfalse (closed)

Fields

agentToolsagentToolsOptionalAgentWorkerToolsConfigExcluded
Explicit agent-loop tool policy for AGENT_WORKER definitions. Omit or set policy DISABLED to run agent loops without advertising or executing tools.
argsargsOptionalarrayExcluded
Additional command arguments passed to the configured command.
authauthOptionalHostedWorkerAuthSelected
Hosted-worker authentication contract. V1 hosted workers accept only auth.secretRef.
bodybodyOptionalstring
Inline worker instructions or script body when the worker is authored directly in factory config.
commandcommandOptionalstringExcluded
Command to execute when this worker runs through a command or script provider.
descriptiondescriptionOptionalNameValue
Optional localized customer-facing explanation of this worker.
executorProviderexecutorProviderOptionalWorkerProviderExcluded
Execution mechanism. Use `ACP` for ACP-backed workers and put the configured integration identity (for example `cursor-acp`) in modelProvider. `SCRIPT_WRAP` remains the command-wrapper compatibility value; legacy named executor identities remain accepted during migration.
ididOptionalstring
Optional durable public identifier for this worker. When present, graph and layout references should use this id instead of the mutable name.
linearlinearOptionalHostedLinearWorkerConfigSelected
Provider-specific configuration for the built-in hosted LINEAR worker.
modelmodelOptionalstringExcluded
Model identifier to request from the configured model provider when this worker uses model execution.
modelLocalitymodelLocalityOptionalWorkerModelLocalityExcluded
Provider locality for this model capability declaration. Use `LOCAL` for embedded or host-managed inference and `CLOUD` for remote provider execution.
modelProvidermodelProviderOptionaloneOfExcluded
Canonical provider identity used for model routing and provider diagnostics, or an exact invocation-parameter placeholder such as `${modelProvider}`. For `executorProvider: ACP`, this names the configured ACP integration, such as `cursor-acp`. Extension identities use lowercase standardized syntax; built-in values such as `CLAUDE` and `CODEX` remain compatibility conveniences.
namenameRequiredstring
Worker name referenced by Workstation.worker.
operationsoperationsOptionalModelOperation[]Excluded
Provider-agnostic model operations that this worker can execute, including named input and output slots.
providerproviderOptionalHostedWorkerProviderSelected
Built-in hosted provider identity when this worker uses repository-owned hosted execution.
reasoningEffortreasoningEffortOptionalReasoningEffort
resourcesresourcesOptionalResourceRequirement[]
Resource capacity this worker requires before it can be dispatched.
skipPermissionsskipPermissionsOptionalbooleanExcluded
When true, bypasses permission checks for providers that support permission gating.
stopTokenstopTokenOptionalstringExcluded
Marker that tells model-oriented workers where to stop generated output when the provider supports it.
timeouttimeoutOptionalstring
Optional Go duration that caps one worker execution attempt.
typetypeOptionalWorkerType
Worker implementation family to instantiate for this definition.

Full Factory schema reference

Examples

Use the minimal valid example when starting a hosted Linear POLLER_WORKER. The misuse example shows an inline API key under auth—V1 hosted workers accept only auth.secretRef, and validation rejects inline credential fields.

Minimal valid POLLER_WORKER:

{
  "name": "linear-poller",
  "type": "POLLER_WORKER",
  "provider": "LINEAR",
  "auth": {
    "secretRef": "secrets/linear-api-key"
  },
  "linear": {
    "pollInterval": "2m",
    "teamIds": [
      "team-a"
    ],
    "stateIds": [
      "state-b"
    ],
    "mapping": {
      "workType": "task",
      "state": "init"
    }
  },
  "body": "Repository-owned Linear poller."
}

Incompatible misuse — inline secret on POLLER_WORKER (rejected):

{
  "name": "linear-poller",
  "type": "POLLER_WORKER",
  "provider": "LINEAR",
  "auth": {
    "apiKey": "lin_api_inline_secret"
  },
  "linear": {
    "pollInterval": "2m",
    "teamIds": [
      "team-a"
    ],
    "stateIds": [
      "state-b"
    ],
    "mapping": {
      "workType": "task",
      "state": "init"
    }
  },
  "body": "Repository-owned Linear poller."
}

auth accepts only secretRef. Validation rejects inline API keys and other credential fields. Resolve the referenced secret from an environment variable or a factory-relative secret file.