Timer

Overview

The Timer events extension emits scheduled event envelopes into Greentic flows. The current runtime discovers timer handlers from installed event extension pack metadata and schedules them by interval_seconds.

Use timer events for:

Daily reports
Periodic cleanup
Scheduled notifications
Regular data sync

Configuration

{
  "events-timer": {
    "enabled": true,
    "timezone": "America/New_York"
  }
}

Configuration Options

Option	Required	Description
`enabled`	Yes	Enable/disable provider
`timezone`	No	Setup metadata for the installed timer extension; use `UTC` unless the pack schema asks for a local timezone

Defining Timer Handlers

Timer handlers are part of the installed timer extension pack metadata, not handwritten YAML in an application bundle. Use gtc wizard to add the timer extension, or inspect the schema first when a coding agent is preparing answers:

gtc wizard --schema
gtc wizard --answers timer-worker-answers.json

A timer-capable extension pack declares handlers in metadata using timer_handlers or timers. The runtime reads that metadata and schedules each handler by interval:

{
  "timer_handlers": [
    {
      "op_id": "timer_digest",
      "handler_id": "daily_digest",
      "interval_seconds": 86400
    }
  ]
}

Timer Event Input

Timer handlers receive a structured tick input:

{
  "v": 1,
  "domain": "events",
  "provider": "events-timer",
  "handler_id": "daily_digest",
  "tenant": "default",
  "team": "default",
  "occurred_at": "2026-04-28T09:00:00Z",
  "interval_seconds": 86400,
  "last_run": "2026-04-27T09:00:00Z"
}

The extension turns the tick into one or more EventEnvelopeV1 events that the event router can send into flows.

Common Intervals

Interval	Seconds	Use case
Every minute	`60`	Fast polling in development or low-cost checks
Every 5 minutes	`300`	Health checks, queue checks, light sync
Hourly	`3600`	Status summaries, periodic reconciliation
Daily	`86400`	Daily reports, maintenance tasks
Weekly	`604800`	Weekly rollups

Examples

Daily Cleanup

nodes:
  - id: cleanup
    type: http
    config:
      method: DELETE
      url: "https://api.example.com/sessions/expired"

triggers:
  - type: timer
    handler: "daily_cleanup"
    target: cleanup

Weekly Summary

nodes:
  - id: generate_summary
    type: llm
    config:
      model: "gpt-4"
      prompt: "Generate weekly summary from: {{data}}"
    to: send_summary

triggers:
  - type: timer
    handler: "weekly_summary"
    target: generate_summary

Periodic Health Check

nodes:
  - id: health_check
    type: http
    config:
      method: GET
      url: "https://api.example.com/health"
    to: check_result

  - id: check_result
    type: branch
    config:
      conditions:
        - expression: "http_response.status != 200"
          to: alert
      default: done

  - id: alert
    type: reply
    config:
      channel: "slack-alerts"
      message: "Health check failed!"

triggers:
  - type: timer
    handler: "health_check"
    target: health_check