From b4e36af6b72625469359d70af499a75370349556 Mon Sep 17 00:00:00 2001 From: Daniel Blignaut Date: Wed, 26 Aug 2026 18:16:46 +0200 Subject: [PATCH] docs(routines): document unified triggers --- chatkit.mdx | 18 ++++++++++++++++++ llms/chatkit.md | 10 ++++++---- llms/state.md | 2 +- terraform.mdx | 2 +- 4 files changed, 26 insertions(+), 6 deletions(-) diff --git a/chatkit.mdx b/chatkit.mdx index 8c2c2dc..d27bee5 100644 --- a/chatkit.mdx +++ b/chatkit.mdx @@ -12,6 +12,24 @@ ChatKit connects an agent endpoint to the places where work begins. It stores se Configure chat providers for conversations from Slack, GitHub, and other supported channels. Use signals when an external event should start or continue a session without first arriving as a chat message. +## Automate work with Routines + +A Routine is one automation with shared ownership, visibility, enablement, and instruction. Each Routine contains one to eight independently enabled triggers. Triggers are OR'd: any matching schedule or event starts a run. + +- **Schedule triggers** use minute-granularity UTC cron expressions. +- **Event triggers** select a configured signal provider, signal type, filters, session policy, and ChatKit action. +- **Manual runs** execute the Routine's default agent and instruction immediately. + +Routine create, trigger replacement, and deletion are atomic. Updates may include `expected_version` to reject concurrent edits instead of overwriting them. Every schedule, event, and manual activation appears in the Routine run history. + +Event triggers support fixed sessions, keyed session reuse, and a new session per delivery. They can invoke an agent or create only a signal message. `instruction_policy` controls whether the agent receives only the normalized signal or both the signal and the Routine instruction. + +Personal signal providers can feed private Routines in a workspace. A personal provider cannot be attached to a team-visible Routine. + + + Signal providers and deliveries remain under Signals. Signal routing rules are now event triggers inside Routines rather than separate resources. + + ## Set up ChatKit diff --git a/llms/chatkit.md b/llms/chatkit.md index 94a644f..e4ea953 100644 --- a/llms/chatkit.md +++ b/llms/chatkit.md @@ -30,17 +30,19 @@ The create response returns the plaintext Tilde API key and webhook signing key Use the Vercel AI Endpoint provider when the user wants to test the agent in [Mission Control](https://api.trytilde.ai/mission-control). -## Trigger work with Signals +## Trigger work with Routines and Signals -Signals turn provider events into ChatKit messages. +Routines unify scheduled and provider-event automation. Signals still owns provider setup, normalized deliveries, deduplication, inspection, and retry. 1. Call `tilde_list_signal_providers` and inspect the selected provider's signal schemas and authentication requirements. 2. Call `tilde_create_signal_provider` with the provider-specific `body`. -3. Call `tilde_create_signal_rule` with a `body` that selects the event type, target agent, action, and stable session-key mapping. +3. Call `tilde_create_routine` with a `body` containing shared fields and one to eight triggers. For an event trigger include `kind: "event"`, `signal_provider_instance_id`, `signal_type`, `filter`, `session_policy`, `action`, and `instruction_policy`. For a schedule trigger include `kind: "schedule"` and a UTC `schedule` cron expression. 4. Use one stable session key when related events should continue the same body of work, such as all updates to one Sentry issue or GitHub pull request. 5. Call `tilde_trigger_fake_signal` to test routing where the provider supports it. 6. Inspect execution with `tilde_list_signal_deliveries`. Use `tilde_retry_signal_delivery` only for a failed delivery that is safe to repeat. -Use `tilde_list_signal_provider_instances` and `tilde_list_signal_rules` before updating or deleting resources. Their mutation functions are `tilde_update_signal_provider`, `tilde_delete_signal_provider`, `tilde_update_signal_rule`, and `tilde_delete_signal_rule`. +Use `tilde_list_signal_provider_instances` and `tilde_list_routines` before updating or deleting resources. Provider mutations are `tilde_update_signal_provider` and `tilde_delete_signal_provider`. Routine mutations are `tilde_update_routine` and `tilde_delete_routine`; pass the current `version` as `expected_version` when replacing triggers. + +Use `enabled` on the Routine as a global override and `enabled` on each trigger for individual control. Event triggers preserve fixed-session, keyed-session, and new-session-per-delivery policies plus both agent-invocation and message-only actions. Use `signal_and_instruction` when the shared Routine instruction must be delivered beside the normalized signal; use `signal_only` to preserve signal-only execution. In application code, handle typed GitHub, Slack, Sentry, and Firecrawl metadata as shown in the [human ChatKit guide](https://trytilde.ai/docs/chatkit). `onUnprocessed` runs once per unprocessed message; later conversions reuse its cached result. diff --git a/llms/state.md b/llms/state.md index dd30ec8..a18b4c8 100644 --- a/llms/state.md +++ b/llms/state.md @@ -1,6 +1,6 @@ # Export and import Tilde state over Global MCP -Tilde resource state is portable even though Tilde does not require Terraform. Keep `tilde.state.yaml` beside a custom agent so another workspace can reproduce its agents, ChatKit providers, tools, MCP servers, skills, wikis, memory bindings, reverse proxies, and relationships. +Tilde resource state is portable even though Tilde does not require Terraform. Keep `tilde.state.yaml` beside a custom agent so another workspace can reproduce its agents, ChatKit providers, unified Routines and their triggers, tools, MCP servers, skills, wikis, memory bindings, reverse proxies, and relationships. State does not contain API keys, signing keys, provider credentials, conversation history, or memory content. diff --git a/terraform.mdx b/terraform.mdx index 13b6b5b..082f7dc 100644 --- a/terraform.mdx +++ b/terraform.mdx @@ -7,7 +7,7 @@ Well, not exactly. Tilde does not require a Terraform provider, but all Tilde re ## The `tilde.state.yaml` file -`tilde.state.yaml` describes the desired configuration for resources in a workspace. It can include ChatKit agents and providers, MCP servers, tool providers, skill registries, wikis, memory-bank bindings, reverse proxies, and their relationships. +`tilde.state.yaml` describes the desired configuration for resources in a workspace. It can include ChatKit agents, providers, unified Routines with schedule and event triggers, MCP servers, tool providers, skill registries, wikis, memory-bank bindings, reverse proxies, and their relationships. State files can declare variables for values that change between environments, such as an agent endpoint URL. They do not contain API keys, signing keys, third-party credentials, conversation history, or other runtime content. An import returns generated values separately and leaves credential-backed resources pending until you connect the corresponding accounts.