threadlight-event-triggers

Files (47)

• SKILL.md
• idempotency-patterns.md · references/
• README.md · references/scaffolds/
• Dockerfile · references/scaffolds/aca-consumer/
• README.md · references/scaffolds/aca-consumer/
• local.test.py · references/scaffolds/aca-consumer/
• pyproject.toml · references/scaffolds/aca-consumer/
• receiver.bicep · references/scaffolds/aca-consumer/
• receiver.py · references/scaffolds/aca-consumer/
• Dockerfile · references/scaffolds/aca-job-cron/
• README.md · references/scaffolds/aca-job-cron/
• local.test.py · references/scaffolds/aca-job-cron/
• pyproject.toml · references/scaffolds/aca-job-cron/
• receiver.bicep · references/scaffolds/aca-job-cron/
• receiver.py · references/scaffolds/aca-job-cron/
• Dockerfile · references/scaffolds/aca-job-manual/
• README.md · references/scaffolds/aca-job-manual/
• local.test.py · references/scaffolds/aca-job-manual/
• pyproject.toml · references/scaffolds/aca-job-manual/
• receiver.bicep · references/scaffolds/aca-job-manual/
• receiver.py · references/scaffolds/aca-job-manual/
• README.md · references/scaffolds/function-eventgrid/
• function_app.py · references/scaffolds/function-eventgrid/
• host.json · references/scaffolds/function-eventgrid/
• local.test.py · references/scaffolds/function-eventgrid/
• receiver_core.py · references/scaffolds/function-eventgrid/
• requirements.txt · references/scaffolds/function-eventgrid/
• README.md · references/scaffolds/function-http/
• function_app.py · references/scaffolds/function-http/
• host.json · references/scaffolds/function-http/
• local.test.py · references/scaffolds/function-http/
• receiver_core.py · references/scaffolds/function-http/
• requirements.txt · references/scaffolds/function-http/
• README.md · references/scaffolds/function-servicebus/
• function_app.py · references/scaffolds/function-servicebus/
• host.json · references/scaffolds/function-servicebus/
• local.test.py · references/scaffolds/function-servicebus/
• receiver_core.py · references/scaffolds/function-servicebus/
• requirements.txt · references/scaffolds/function-servicebus/
• _scaffold_harness.py · tests/
• test_aca_consumer.py · tests/
• test_aca_job_cron.py · tests/
• test_aca_job_manual.py · tests/
• test_function_eventgrid.py · tests/
• test_function_http.py · tests/
• test_function_servicebus.py · tests/
• test_scaffolds_shipped.py · tests/

SKILL.md (first lines)

# Threadlight Event Triggers

Generate non-interactive trigger receivers (ACA jobs, ACA HTTP apps, ACA
consumers with KEDA, optionally Functions) for a threadlight process,
based on `specs/SPEC.md` § 10b.

> **Why a separate skill from `threadlight-deploy/references/azd-modules`?** `threadlight-deploy/references/azd-modules` documents
> the ACA-job *deployment* pattern (Bicep, postdeploy hook, image update).
> This skill is one level up: given a spec, it picks the right
> receiver shape, generates the receiver code, wires idempotency and
> dead-letter rules, and emits the right Bicep that `threadlight-deploy/references/azd-modules`
> teaches how to deploy. They're complementary.

## When to Use

- Process spec § 10 declares `Trigger: scheduled` or `event-driven`
- Process needs a webhook receiver from an external system
- Process needs a periodic job (e.g. nightly batch, hourly KPI rollup)
- Process needs to consume from Service Bus / Event Grid

## When NOT to Use

- Process is `on-demand` only (chat-triggered through the agent itself)
- Process is `continuous` streaming (different scaffold — needs Stream Analytics
  or Event Hubs consumer; not yet covered in this skill)
- The trigger logic is part of the agent's reasoning (e.g. agent decides
  to schedule a follow-up) — that lives in the agent skill, not here

---

## ACA-first stance

Every receiver in this skill defaults to **Azure Container Apps**. We chose
this for production-grade threadlight pilots over Azure Functions for
boring-but-real reasons:

| Functions pain in production | ACA equivalent / mitigation |
|------------------------------|-----------------------------|
| Cold starts (5-10s on Consumption; better-but-not-zero on Flex) | ACA `minReplicas: 1` keeps a warm replica; Jobs are launched on demand without an idle tax |
| Programming-model split (v1 vs v2 Python decorators, in-proc vs isolated .NET) | One model: a regular container running your framework of choice |
| `host.json` / `local.settings.json` / `function.json` politics | One `Dockerfile`, one `azure.yaml`, one Bicep |
| Bindings hide failures behind generic 500s; `func` runtime lags Azure | Direct SDK calls in the container; same code runs locally with `docker run` |
| Identity / UAMI sometimes silently ignored by the binding extension | UAMI is a first-class `identity:` block on the container; predictable |
| Time-bound (10 min default, 60 min Premium) — kills long agent loops | Jobs `replicaTimeout` up to 24h; apps run indefinitely |
| Scaling rules less expressive than KEDA | ACA *is* KEDA — full scaler catalog (SB, Event Grid, Cosmos, Kafka, Cron, custom) |
| App Insights auto-instrumentation conflicts with manual OTel | Bring your own OTel SDK, exports cleanly to App Insights / Foundry traces |

**This is not "Functions are bad"** — they're great for hobby-scale or
narrowly-scoped HTTP webhooks where a customer is already deeply invested
in the Functions ecosystem. But the threadlight value prop ("we deliver
this reliably") is undermined when day-3 of the pilot turns into a
debug-the-binding session.

ACA is the default. Functions appear in this skill only as **escape-hatch
shapes** — call them out explicitly if you reach for one (see § "When to
choose Functions anyway" below).

---

## Input contract / Output artifacts

**Input contract**:

- `specs/SPEC.md` § 10b **Triggers (Receiver contract)** — required:
  - `Trigger source` (cron expression, event topic, queue name, webhook URL)
  - `Receiver type` (ACA Job / ACA App / ACA Consumer / Function — last only when justified)
  - `Idempotency key` (field name or `none`)
  - `Dedup window`
  - `Dead-letter rule`
- `specs/SPEC.md` § 10 — for SLA/concurrency context
- `specs/SPEC.md` § 6 — for the agent invocation contract (the receiver
  ultimately calls the agent)
- `specs/SPEC.md` § 11c (Tech Stack) — confirms `event-grid`, `service-bus`,
  or `aca-job` is selected

**Output**:

```
src/triggers/
├── {trigger-name}/
│   ├── receiver.py            # The receiver entry point
│   ├── pyproject.toml         # uv-managed deps
│   ├── Dockerfile             # for ALL ACA receivers (Job / App / Consumer)
│   └── README.md              # how to test locally + idempotency notes
infra/triggers/
├── {trigger-name}.bicep       # ACA Job / App / Consumer / (Function escape hatch)
└── dead-letter.bicep          # Storage Queue / SB DLQ / etc.
```

Plus updates to:
- `azure.yaml` — register the new service
- `infra/main.bicep` — wire the trigger module
- `scripts/postdeploy.py` — for ACA Job image updates (per `threadlight-deploy/references/azd-modules`)

> **Kratos-export mode.** This skill layers cleanly onto a **Kratos-exported
> project** (`src/hosted-agent/` + `use-cases/<x>/`, trimmed `infra/` — see
> [`docs/KRATOS-BRIDGE.md`](../../docs/KRATOS-BRIDGE.md)). The receiver scaffold
> still lands under `src/triggers/` and `infra/triggers/`, and the trimmed Kratos
> `infra/main.bicep` + `azure.yaml` are the registration targets. There is no
> `specs/SPEC.md` § 10b in an export, so take the receiver contract (source,
> type, idempotency key, dedup window, dead-letter rule) **from the operator**,
> and point the receiver's agent invocation at the export's hosted agent
> (`src/hosted-agent/` / `agent.manifest.yaml`). If the trigger also needs a new
> agent skill, scaffold it at the resolved skills root (`use-cases/<x>/skills/`
> in export mode; `--skills-root` to override).

---

## The receiver shapes (ACA-first)

| # | Shape | When | Where it runs |
|---|-------|------|---------------|
| 1 | **ACA Job (cron)** | Periodic batch; latency tolerance >1 min | Container Apps Job, scheduled trigger |
| 2 | **ACA Job (manual)** | Webhook receiver invokes via REST; or part of a workflow | Container Apps Job, manual trigger via REST `start` |
| 3 | **ACA App (HTTP)** | Webhook receiver; low-medium throughput; needs sub-second response | Container App with HTTP ingress, `minReplicas: 1` |
| 4 | **ACA Consumer (KEDA)** | Service Bus / Event Grid / Event Hubs / Cosmos change feed / Kafka | Container App with KEDA scaler; scales to zero between events |
| 5 | **Function (escape hatch)** | See § "When to choose Functions anyway" — narrow cases only | Function App (Flex Consumption preferred) |

**Default for most threadlight processes**:

From aiappsgbb/threadlight-skills, MIT.

More from aiappsgbb/threadlight-skills