feat(connectors): check workflow and trigger references against the capabilities a connector declares #2087

Closed
opened 2026-11-21 06:06:51 +00:00 by sam · 1 comment
Owner

A connector already describes itself: Describe lists its event types, actions, deliveries and lookups with JSON Schemas, and says whether it listens or answers target facts. Core uses that only at run time. A workflow or trigger can name an action, event type or channel the connector doesn't have, and nothing says so until a run fails. message.send is the one exception (#2085), and it checks a hard-coded delivery name against the running connector only.

The Terraform provider model is the pattern: one generic contract, extensions declare what they can do, and core checks configuration against those declarations before anything runs. A new kind of integration is then a new capability, not a new contract.

Scope

  1. The connectors module stores each accepted connector's declarations when the connector loads, and keeps them while it is stopped, so a check doesn't depend on the process being up. A connector that has never loaded has no capabilities.
  2. One API in the connectors module answers whether a connector declares a capability (kind and name) and returns its schema.
  3. Saving a workflow, or starting a dry run, refuses:
    • a connector.action step whose connector doesn't declare the action, or whose literal input fails the action's input schema (templated values are checked at run time as now);
    • a message.send step whose channel doesn't declare chat_message, using the same API instead of the special case.
  4. Saving a trigger refuses an event type that the source's connector doesn't declare. Schedule triggers are exempt.
  5. The dashboard's extension page lists each connector's declared capabilities.

Guards, secret engines and MCP servers stay separate contracts. Guards and secret engines sit on a different trust boundary, and MCP is an external protocol.

Done when

  • Each refusal above returns a problem at the offending field, and a valid workflow and trigger still save.
  • A test table in modules/runs covers an undeclared action, input that fails its schema, and an undeclared channel; one in modules/events covers an undeclared event type.
  • task check passes.
A connector already describes itself: `Describe` lists its event types, actions, deliveries and lookups with JSON Schemas, and says whether it listens or answers target facts. Core uses that only at run time. A workflow or trigger can name an action, event type or channel the connector doesn't have, and nothing says so until a run fails. `message.send` is the one exception (#2085), and it checks a hard-coded delivery name against the running connector only. The Terraform provider model is the pattern: one generic contract, extensions declare what they can do, and core checks configuration against those declarations before anything runs. A new kind of integration is then a new capability, not a new contract. ## Scope 1. The connectors module stores each accepted connector's declarations when the connector loads, and keeps them while it is stopped, so a check doesn't depend on the process being up. A connector that has never loaded has no capabilities. 2. One API in the connectors module answers whether a connector declares a capability (kind and name) and returns its schema. 3. Saving a workflow, or starting a dry run, refuses: - a `connector.action` step whose connector doesn't declare the action, or whose literal input fails the action's input schema (templated values are checked at run time as now); - a `message.send` step whose channel doesn't declare `chat_message`, using the same API instead of the special case. 4. Saving a trigger refuses an event type that the source's connector doesn't declare. Schedule triggers are exempt. 5. The dashboard's extension page lists each connector's declared capabilities. Guards, secret engines and MCP servers stay separate contracts. Guards and secret engines sit on a different trust boundary, and MCP is an external protocol. ## Done when - Each refusal above returns a problem at the offending field, and a valid workflow and trigger still save. - A test table in `modules/runs` covers an undeclared action, input that fails its schema, and an undeclared channel; one in `modules/events` covers an undeclared event type. - `task check` passes.
sam added the in-progressfeaturelow labels 2026-11-21 06:06:51 +00:00
Author
Owner

Merged in 9c0da0780 (feature commit 14060675c). Migration 00046 stores each connector's declarations when it loads. Saving a workflow or starting a dry run refuses an undeclared action, literal action input that fails its schema, and a message.send channel without chat_message; input holding a reference is still checked at run time. Saving a trigger refuses an event type the source's connector doesn't declare (schedule triggers are exempt) and a source that doesn't exist. The connectors list in the dashboard shows what each connector declares. Tables in modules/runs and modules/events cover each refusal, each proved to fail with its check removed. task check passed on the merged tree. Not run against a live connector on staging.

Merged in 9c0da0780 (feature commit 14060675c). Migration 00046 stores each connector's declarations when it loads. Saving a workflow or starting a dry run refuses an undeclared action, literal action input that fails its schema, and a message.send channel without chat_message; input holding a reference is still checked at run time. Saving a trigger refuses an event type the source's connector doesn't declare (schedule triggers are exempt) and a source that doesn't exist. The connectors list in the dashboard shows what each connector declares. Tables in modules/runs and modules/events cover each refusal, each proved to fail with its check removed. task check passed on the merged tree. Not run against a live connector on staging.
sam closed this issue 2026-11-21 06:18:12 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sam/archie#2087