/**
* std/triggers — typed trigger envelopes shared across inbound providers.
*
* Import with: `import "std/triggers"`.
*
* The runtime persists RFC3339 timestamps, typed signature status, and a
* provider-tagged payload union. Connector-specific payloads intentionally
* start with a small normalized surface plus `raw: dict`; provider tickets can
* refine these aliases later without changing the top-level TriggerEvent shape.
*/
type ProviderId = "github" | "slack" | "linear" | "notion" | "cron" | "webhook" | "a2a-push" | "kafka" | "nats" | "pulsar" | "postgres-cdc" | "email" | "websocket" | string
type SignatureVerified = {state: "verified"}
type SignatureUnsigned = {state: "unsigned"}
type SignatureFailed = {state: "failed", reason: string}
type SignatureStatus = SignatureVerified | SignatureUnsigned | SignatureFailed
type GitHubIssuesEventPayload = {
provider: "github",
event: "issues",
action: string?,
delivery_id: string?,
installation_id: int?,
topic: string?,
repository: dict?,
repo: dict?,
issue: dict,
raw: dict,
}
type GitHubPullRequestEventPayload = {
provider: "github",
event: "pull_request",
action: string?,
delivery_id: string?,
installation_id: int?,
topic: string?,
repository: dict?,
repo: dict?,
pull_request: dict,
raw: dict,
}
type GitHubIssueCommentEventPayload = {
provider: "github",
event: "issue_comment",
action: string?,
delivery_id: string?,
installation_id: int?,
topic: string?,
repository: dict?,
repo: dict?,
issue: dict,
comment: dict,
raw: dict,
}
type GitHubPullRequestReviewEventPayload = {
provider: "github",
event: "pull_request_review",
action: string?,
delivery_id: string?,
installation_id: int?,
topic: string?,
repository: dict?,
repo: dict?,
pull_request: dict,
review: dict,
raw: dict,
}
type GitHubPushEventPayload = {
provider: "github",
event: "push",
action: string?,
delivery_id: string?,
installation_id: int?,
topic: string?,
repository: dict?,
repo: dict?,
commits: list<dict>,
distinct_size: int?,
raw: dict,
}
type GitHubWorkflowRunEventPayload = {
provider: "github",
event: "workflow_run",
action: string?,
delivery_id: string?,
installation_id: int?,
topic: string?,
repository: dict?,
repo: dict?,
workflow_run: dict,
raw: dict,
}
type GitHubDeploymentStatusEventPayload = {
provider: "github",
event: "deployment_status",
action: string?,
delivery_id: string?,
installation_id: int?,
topic: string?,
repository: dict?,
repo: dict?,
deployment_status: dict,
deployment: dict,
raw: dict,
}
type GitHubCheckRunEventPayload = {
provider: "github",
event: "check_run",
action: string?,
delivery_id: string?,
installation_id: int?,
topic: string?,
repository: dict?,
repo: dict?,
check_run: dict,
raw: dict,
}
type GitHubCheckSuiteEventPayload = {
provider: "github",
event: "check_suite",
action: string?,
delivery_id: string?,
installation_id: int?,
topic: string?,
repository: dict?,
repo: dict?,
check_suite: dict,
check_suite_id: int?,
pull_request_number: int?,
head_sha: string?,
head_ref: string?,
base_ref: string?,
status: string?,
conclusion: string?,
raw: dict,
}
type GitHubStatusEventPayload = {
provider: "github",
event: "status",
action: string?,
delivery_id: string?,
installation_id: int?,
topic: string?,
repository: dict?,
repo: dict?,
commit_status: dict?,
status_id: int?,
head_sha: string?,
head_ref: string?,
base_ref: string?,
state: string?,
context: string?,
target_url: string?,
raw: dict,
}
type GitHubMergeGroupEventPayload = {
provider: "github",
event: "merge_group",
action: string?,
delivery_id: string?,
installation_id: int?,
topic: string?,
repository: dict?,
repo: dict?,
merge_group: dict,
merge_group_id: any,
head_sha: string?,
head_ref: string?,
base_sha: string?,
base_ref: string?,
pull_requests: list<dict>,
pull_request_numbers: list<int>,
raw: dict,
}
type GitHubInstallationEventPayload = {
provider: "github",
event: "installation",
action: string?,
delivery_id: string?,
installation_id: int?,
topic: string?,
repository: dict?,
repo: dict?,
installation: dict?,
account: dict?,
installation_state: string?,
suspended: bool?,
revoked: bool?,
repositories: list<dict>,
raw: dict,
}
type GitHubInstallationRepositoriesEventPayload = {
provider: "github",
event: "installation_repositories",
action: string?,
delivery_id: string?,
installation_id: int?,
topic: string?,
repository: dict?,
repo: dict?,
installation: dict?,
account: dict?,
installation_state: string?,
suspended: bool?,
revoked: bool?,
repository_selection: string?,
repositories_added: list<dict>,
repositories_removed: list<dict>,
raw: dict,
}
type GitHubOtherEventPayload = {
provider: "github",
event: string,
action: string?,
delivery_id: string?,
installation_id: int?,
topic: string?,
repository: dict?,
repo: dict?,
raw: dict,
}
type GitHubEventPayload = GitHubIssuesEventPayload | GitHubPullRequestEventPayload | GitHubIssueCommentEventPayload | GitHubPullRequestReviewEventPayload | GitHubPushEventPayload | GitHubWorkflowRunEventPayload | GitHubDeploymentStatusEventPayload | GitHubCheckRunEventPayload | GitHubCheckSuiteEventPayload | GitHubStatusEventPayload | GitHubMergeGroupEventPayload | GitHubInstallationEventPayload | GitHubInstallationRepositoriesEventPayload | GitHubOtherEventPayload
type SlackEventCommon = {
provider: "slack",
event: string,
event_id: string?,
api_app_id: string?,
team_id: string?,
channel_id: string?,
user_id: string?,
event_ts: string?,
raw: dict,
}
type SlackMessageEventPayload = {
provider: "slack",
event: string,
event_id: string?,
api_app_id: string?,
team_id: string?,
channel_id: string?,
user_id: string?,
event_ts: string?,
subtype: string?,
channel_type: string?,
channel: string?,
user: string?,
text: string?,
ts: string?,
thread_ts: string?,
raw: dict,
}
type SlackAppMentionEventPayload = {
provider: "slack",
event: "app_mention",
event_id: string?,
api_app_id: string?,
team_id: string?,
channel_id: string?,
user_id: string?,
event_ts: string?,
channel: string?,
user: string?,
text: string?,
ts: string?,
thread_ts: string?,
raw: dict,
}
type SlackReactionAddedEventPayload = {
provider: "slack",
event: "reaction_added",
event_id: string?,
api_app_id: string?,
team_id: string?,
channel_id: string?,
user_id: string?,
event_ts: string?,
reaction: string?,
item_user: string?,
item: dict,
raw: dict,
}
type SlackAppHomeOpenedEventPayload = {
provider: "slack",
event: "app_home_opened",
event_id: string?,
api_app_id: string?,
team_id: string?,
channel_id: string?,
user_id: string?,
event_ts: string?,
user: string?,
channel: string?,
tab: string?,
view: dict,
raw: dict,
}
type SlackAssistantThreadStartedEventPayload = {
provider: "slack",
event: "assistant_thread_started",
event_id: string?,
api_app_id: string?,
team_id: string?,
channel_id: string?,
user_id: string?,
event_ts: string?,
assistant_thread: dict,
thread_ts: string?,
context: dict,
raw: dict,
}
type SlackOtherEventPayload = {
provider: "slack",
event: string,
event_id: string?,
api_app_id: string?,
team_id: string?,
channel_id: string?,
user_id: string?,
event_ts: string?,
raw: dict,
}
type SlackEventPayload = SlackMessageEventPayload | SlackAppMentionEventPayload | SlackReactionAddedEventPayload | SlackAppHomeOpenedEventPayload | SlackAssistantThreadStartedEventPayload | SlackOtherEventPayload
type LinearEventCommon = {
provider: "linear",
event: string,
action: string?,
delivery_id: string?,
organization_id: string?,
webhook_timestamp: int?,
webhook_id: string?,
url: string?,
created_at: string?,
actor: dict?,
raw: dict,
}
type LinearIssueTitleChange = {field_name: "title", previous: string?}
type LinearIssueDescriptionChange = {field_name: "description", previous: string?}
type LinearIssuePriorityChange = {field_name: "priority", previous: int?}
type LinearIssueEstimateChange = {field_name: "estimate", previous: int?}
type LinearIssueStateIdChange = {field_name: "state_id", previous: string?}
type LinearIssueTeamIdChange = {field_name: "team_id", previous: string?}
type LinearIssueAssigneeIdChange = {field_name: "assignee_id", previous: string?}
type LinearIssueProjectIdChange = {field_name: "project_id", previous: string?}
type LinearIssueCycleIdChange = {field_name: "cycle_id", previous: string?}
type LinearIssueDueDateChange = {field_name: "due_date", previous: string?}
type LinearIssueParentIdChange = {field_name: "parent_id", previous: string?}
type LinearIssueSortOrderChange = {field_name: "sort_order", previous: float?}
type LinearIssueLabelIdsChange = {field_name: "label_ids", previous: list<string>}
type LinearIssueCompletedAtChange = {field_name: "completed_at", previous: string?}
type LinearIssueOtherChange = {field_name: "other", field: string, previous: any}
type LinearIssueChange = LinearIssueTitleChange | LinearIssueDescriptionChange | LinearIssuePriorityChange | LinearIssueEstimateChange | LinearIssueStateIdChange | LinearIssueTeamIdChange | LinearIssueAssigneeIdChange | LinearIssueProjectIdChange | LinearIssueCycleIdChange | LinearIssueDueDateChange | LinearIssueParentIdChange | LinearIssueSortOrderChange | LinearIssueLabelIdsChange | LinearIssueCompletedAtChange | LinearIssueOtherChange
type LinearIssueEventPayload = {
provider: "linear",
event: "issue",
action: string?,
delivery_id: string?,
organization_id: string?,
webhook_timestamp: int?,
webhook_id: string?,
url: string?,
created_at: string?,
actor: dict?,
issue: dict,
changes: list<LinearIssueChange>,
raw: dict,
}
type LinearIssueCommentEventPayload = {
provider: "linear",
event: "comment",
action: string?,
delivery_id: string?,
organization_id: string?,
webhook_timestamp: int?,
webhook_id: string?,
url: string?,
created_at: string?,
actor: dict?,
comment: dict,
raw: dict,
}
type LinearIssueLabelEventPayload = {
provider: "linear",
event: "issue_label",
action: string?,
delivery_id: string?,
organization_id: string?,
webhook_timestamp: int?,
webhook_id: string?,
url: string?,
created_at: string?,
actor: dict?,
label: dict,
raw: dict,
}
type LinearProjectEventPayload = {
provider: "linear",
event: "project",
action: string?,
delivery_id: string?,
organization_id: string?,
webhook_timestamp: int?,
webhook_id: string?,
url: string?,
created_at: string?,
actor: dict?,
project: dict,
raw: dict,
}
type LinearCycleEventPayload = {
provider: "linear",
event: "cycle",
action: string?,
delivery_id: string?,
organization_id: string?,
webhook_timestamp: int?,
webhook_id: string?,
url: string?,
created_at: string?,
actor: dict?,
cycle: dict,
raw: dict,
}
type LinearCustomerEventPayload = {
provider: "linear",
event: "customer",
action: string?,
delivery_id: string?,
organization_id: string?,
webhook_timestamp: int?,
webhook_id: string?,
url: string?,
created_at: string?,
actor: dict?,
customer: dict,
raw: dict,
}
type LinearCustomerRequestEventPayload = {
provider: "linear",
event: "customer_request",
action: string?,
delivery_id: string?,
organization_id: string?,
webhook_timestamp: int?,
webhook_id: string?,
url: string?,
created_at: string?,
actor: dict?,
customer_request: dict,
raw: dict,
}
type LinearOtherEventPayload = LinearEventCommon
type LinearEventPayload = LinearIssueEventPayload | LinearIssueCommentEventPayload | LinearIssueLabelEventPayload | LinearProjectEventPayload | LinearCycleEventPayload | LinearCustomerEventPayload | LinearCustomerRequestEventPayload | LinearOtherEventPayload
type NotionPolledChangeEvent = {
resource: string,
source_id: string,
entity_id: string,
high_water_mark: string,
before: dict?,
after: dict,
}
type NotionEventCommon = {
provider: "notion",
event: string,
workspace_id: string?,
request_id: string?,
subscription_id: string?,
integration_id: string?,
attempt_number: int?,
entity_id: string?,
entity_type: string?,
api_version: string?,
verification_token: string?,
polled: NotionPolledChangeEvent?,
raw: dict,
}
type NotionSubscriptionVerificationEventPayload = {
provider: "notion",
event: "subscription.verification",
workspace_id: string?,
request_id: string?,
subscription_id: string?,
integration_id: string?,
attempt_number: int?,
entity_id: string?,
entity_type: string?,
api_version: string?,
verification_token: string?,
polled: NotionPolledChangeEvent?,
raw: dict,
}
type NotionPageContentUpdatedEventPayload = {
provider: "notion",
event: "page.content_updated",
workspace_id: string?,
request_id: string?,
subscription_id: string?,
integration_id: string?,
attempt_number: int?,
entity_id: string?,
entity_type: string?,
api_version: string?,
verification_token: string?,
polled: NotionPolledChangeEvent?,
raw: dict,
}
type NotionPageLockedEventPayload = {
provider: "notion",
event: "page.locked",
workspace_id: string?,
request_id: string?,
subscription_id: string?,
integration_id: string?,
attempt_number: int?,
entity_id: string?,
entity_type: string?,
api_version: string?,
verification_token: string?,
polled: NotionPolledChangeEvent?,
raw: dict,
}
type NotionCommentCreatedEventPayload = {
provider: "notion",
event: "comment.created",
workspace_id: string?,
request_id: string?,
subscription_id: string?,
integration_id: string?,
attempt_number: int?,
entity_id: string?,
entity_type: string?,
api_version: string?,
verification_token: string?,
polled: NotionPolledChangeEvent?,
raw: dict,
}
type NotionDataSourceSchemaUpdatedEventPayload = {
provider: "notion",
event: "data_source.schema_updated",
workspace_id: string?,
request_id: string?,
subscription_id: string?,
integration_id: string?,
attempt_number: int?,
entity_id: string?,
entity_type: string?,
api_version: string?,
verification_token: string?,
polled: NotionPolledChangeEvent?,
raw: dict,
}
type NotionPolledEventPayload = {
provider: "notion",
event: "page.content_updated",
workspace_id: string?,
request_id: string?,
subscription_id: string?,
integration_id: string?,
attempt_number: int?,
entity_id: string?,
entity_type: string?,
api_version: string?,
verification_token: string?,
polled: NotionPolledChangeEvent,
raw: dict,
}
type NotionOtherEventPayload = {
provider: "notion",
event: string,
workspace_id: string?,
request_id: string?,
subscription_id: string?,
integration_id: string?,
attempt_number: int?,
entity_id: string?,
entity_type: string?,
api_version: string?,
verification_token: string?,
polled: NotionPolledChangeEvent?,
raw: dict,
}
type NotionEventPayload = NotionSubscriptionVerificationEventPayload | NotionPageContentUpdatedEventPayload | NotionPageLockedEventPayload | NotionCommentCreatedEventPayload | NotionDataSourceSchemaUpdatedEventPayload | NotionPolledEventPayload | NotionOtherEventPayload
type CronEventPayload = {
provider: "cron",
cron_id: string?,
schedule: string?,
tick_at: string,
raw: dict,
}
type GenericWebhookPayload = {
provider: "webhook",
source: string?,
content_type: string?,
raw: dict,
}
type A2aPushPayload = {
provider: "a2a-push",
task_id: string?,
task_state: string?,
artifact: any?,
sender: string?,
raw: dict,
kind: string,
}
type StreamEventPayload = {
provider: "kafka" | "nats" | "pulsar" | "postgres-cdc" | "email" | "websocket",
event: string,
source: string?,
stream: string?,
partition: string?,
offset: string?,
key: string?,
timestamp: string?,
headers: dict,
raw: dict,
}
type ExtensionProviderPayload = {provider: string, schema_name: string, raw: dict}
type ProviderPayload = GitHubEventPayload | SlackEventPayload | LinearEventPayload | NotionEventPayload | CronEventPayload | GenericWebhookPayload | A2aPushPayload | StreamEventPayload | ExtensionProviderPayload
type ProviderSecretRequirement = {name: string, required: bool, namespace: string}
type ProviderOutboundMethod = {name: string}
type ProviderSignatureVerificationNone = {kind: "none"}
type ProviderSignatureVerificationHmac = {
kind: "hmac",
variant: string,
raw_body: bool,
signature_header: string,
timestamp_header: string?,
id_header: string?,
default_tolerance_secs: int?,
digest: string,
encoding: string,
}
type ProviderSignatureVerification = ProviderSignatureVerificationNone | ProviderSignatureVerificationHmac
type ProviderRuntimeBuiltin = {
kind: "builtin",
connector: string,
default_signature_variant: string?,
}
type ProviderRuntimePlaceholder = {kind: "placeholder"}
type ProviderRuntime = ProviderRuntimeBuiltin | ProviderRuntimePlaceholder
type ProviderCatalogEntry = {
provider: string,
kinds: list<string>,
schema_name: string,
outbound_methods: list<ProviderOutboundMethod>,
secret_requirements: list<ProviderSecretRequirement>,
signature_verification: ProviderSignatureVerification,
runtime: ProviderRuntime,
}
type TriggerEvent = {
id: string,
provider: ProviderId,
kind: string,
received_at: string,
occurred_at: string?,
dedupe_key: string,
trace_id: string,
tenant_id: string?,
headers: dict,
batch: list<dict>?,
raw_body: bytes?,
provider_payload: ProviderPayload,
signature_status: SignatureStatus,
}
type TriggerState = "registering" | "active" | "draining" | "terminated"
type TriggerBindingSource = "manifest" | "dynamic"
type TriggerHandler = fn(TriggerEvent) -> any | string
type TriggerPredicate = fn(TriggerEvent) -> bool | Result<bool, any>
type TriggerMatch = {events: list<string>?}
type TriggerBudget = {
max_cost_usd: float?,
max_tokens: int?,
daily_cost_usd: float?,
hourly_cost_usd: float?,
max_concurrent: int?,
on_budget_exhausted: string?,
}
type TriggerWhenBudget = {max_cost_usd: float?, tokens_max: int?, timeout: string?}
type TriggerRetryBackoff = "svix" | "immediate"
type TriggerRetry = {max: int?, backoff: TriggerRetryBackoff?}
type AutonomyTier = "shadow" | "suggest" | "act_with_approval" | "act_auto"
type TrustOutcome = "success" | "failure" | "denied" | "timeout"
type TriggerConfig = {
id: string?,
kind: string,
provider: ProviderId,
autonomy_tier: AutonomyTier?,
handler: TriggerHandler,
when: TriggerPredicate?,
when_budget: TriggerWhenBudget?,
retry: TriggerRetry?,
match: TriggerMatch?,
events: list<string>?,
dedupe_key: string?,
filter: string?,
allow_cleartext: bool?,
budget: TriggerBudget?,
manifest_path: string?,
package_name: string?,
}
type TriggerMetrics = {
received: int,
dispatched: int,
failed: int,
dlq: int,
in_flight: int,
last_received_ms: int?,
cost_total_usd_micros: int,
cost_today_usd_micros: int,
cost_hour_usd_micros: int,
}
type TriggerBinding = {
id: string,
version: int,
source: TriggerBindingSource,
kind: string,
provider: string,
autonomy_tier: AutonomyTier,
handler_kind: string,
state: TriggerState,
metrics: TriggerMetrics,
daily_cost_usd: float?,
hourly_cost_usd: float?,
on_budget_exhausted: string,
}
type TriggerHandle = TriggerBinding
type DispatchHandle = {
event_id: string,
binding_id: string,
binding_version: int,
status: string,
replay_of_event_id: string?,
dlq_entry_id: string?,
error: string?,
result: any?,
}
type DlqAttempt = {attempt: int, at: string, status: string, error: string?}
type DlqEntry = {
id: string,
event_id: string,
binding_id: string,
binding_version: int,
provider: string,
kind: string,
state: string,
error: string,
error_class: string,
event: TriggerEvent,
retry_history: list<DlqAttempt>,
}
type TriggerActionGraphEvent = {kind: string, headers: dict, payload: dict}
type TrustEntryId = string
type CapabilityPolicy = {
tools: list<string>,
capabilities: dict,
workspace_roots: list<string>,
side_effect_level: string?,
recursion_limit: int?,
tool_arg_constraints: list<dict>,
tool_annotations: dict,
}
type TrustRecord = {
schema: string,
record_id: string,
agent: string,
action: string,
approver: string?,
outcome: TrustOutcome,
trace_id: string,
autonomy_tier: AutonomyTier,
timestamp: string,
cost_usd: float?,
chain_index: int,
previous_hash: string?,
entry_hash: string,
metadata: dict,
}
type TrustTraceGroup = {trace_id: string, records: list<TrustRecord>}
type TrustQueryFilters = {
agent: string?,
action: string?,
since: string?,
until: string?,
tier: AutonomyTier?,
outcome: TrustOutcome?,
limit: int?,
grouped_by_trace: bool?,
}
type TrustScore = {
agent: string,
action: string?,
total: int,
successes: int,
failures: int,
denied: int,
timeouts: int,
success_rate: float,
latest_outcome: TrustOutcome?,
latest_timestamp: string?,
effective_tier: AutonomyTier,
policy: CapabilityPolicy,
}
type TrustChainReport = {
topic: string,
total: int,
verified: bool,
root_hash: string?,
broken_at_event_id: int?,
errors: list<string>,
}
type HandlerContext = {
agent: string,
action: string,
trace_id: string,
replay_of_event_id: string?,
autonomy_tier: AutonomyTier,
trigger_event: TriggerEvent,
}
type StreamWindowMode = "tumbling" | "sliding" | "session"
type StreamWindowSpec = {
mode: StreamWindowMode,
key: string?,
size: string?,
every: string?,
gap: string?,
max_items: int?,
}
type StreamForkPlan = {kind: "stream.fork", source: any, branches: list<any>}
type StreamJoinPlan = {kind: "stream.join", source: any, join: dict}
type StreamWindowPlan = {kind: "stream.window", events: list<any>, window: StreamWindowSpec}
type StreamLlmClassifyPlan = {
kind: "stream.llm_classify",
input: any,
labels: list<string>,
cache: string?,
options: dict,
}
/** list_providers. */
pub fn list_providers() -> list<ProviderCatalogEntry> {
return list_providers_native()
}
/** stream_fork returns a declarative fan-out plan for stream handlers. */
pub fn stream_fork(source, branches = []) -> StreamForkPlan {
return {kind: "stream.fork", source: source, branches: branches}
}
/** stream_join returns a declarative fan-in plan for stream handlers. */
pub fn stream_join(source, join = nil) -> StreamJoinPlan {
return {kind: "stream.join", source: source, join: join ?? {}}
}
/** window_by groups stream events with the same manifest window shape. */
pub fn window_by(events, window: StreamWindowSpec) -> StreamWindowPlan {
return {kind: "stream.window", events: events, window: window}
}
/**
* llm_classify describes a cached classifier step without forcing a provider call during planning.
*/
pub fn llm_classify(input, labels, options = nil) -> StreamLlmClassifyPlan {
let config = options ?? {}
return {kind: "stream.llm_classify", input: input, labels: labels, cache: config?.cache, options: config}
}