Changelog
All notable changes to this project are documented here. The format follows Keep a Changelog, and the project uses Semantic Versioning. How to cut a release is in docs/DEVELOPMENT.md.
[Unreleased]
Section titled “[Unreleased]”[1.5.0] - 2026-11-12
Section titled “[1.5.0] - 2026-11-12”The editor now shows which {{variables}} will resolve, and edits an HTTP Request’s
response mapping, headers and body as rows. One change for operators: the text log
format’s separator (see Changed); LOG_FORMAT=json, which the monitoring profile reads,
is unchanged.
{{variables}}are coloured as you type: green when the name resolves (a call field, a flow variable, a declared env var, or a name some component stores into), red with a wavy underline when nothing sets it, so it would be empty at run time. Hovering the field names the red ones./validatenow also returnsvariables, the names the flow’s components store into.- HTTP Request’s Response Mapping, Headers and Body are rows. A mapping row is a path and the variable to save it as, with a one-click fix for a JSONPath or bracket path and a sample-JSON picker. Headers and Body are name → value rows with a Rows | JSON switch; a body holding a number, true/false, a list or a nested object opens as JSON. An empty body sends no body.
Changed
Section titled “Changed”- HTTP Request’s method sits before its URL, on one line.
- The component list shows no tooltip on hover. The description is on the component’s Properties pane.
- The text log format separates the logger from the message with
:(was an em dash):INFO app.audit: ….LOG_FORMAT=jsonis unchanged. Anything that parses the text format by that separator needs the new one. - No em-dashes in the app’s messages, UI or docs. Log, error and validation
messages keep their wording; only the punctuation around each dash changed. A missing
timestamp shows
-, and an empty dropdown choice reads(none). - Dependencies (development and monitoring only): the build stage’s uv image
(digest e80c05a3), CI’s
setup-uvv10.3.3 (was v10.3.2), and the monitoring profile’s Prometheus v3.16.0 (was v3.15.1). The app’s own Python dependencies are unchanged.
[1.4.2] - 2026-11-10
Section titled “[1.4.2] - 2026-11-10”A security update: oauthlib moves to the release that actually closes the advisory 1.4.1
was cut for, and the runtime image’s base is refreshed. The v1.4.1 tag’s image scan
failed on both, so upgrade from 1.3.1 straight to 1.4.2; 1.4.0’s notes below apply.
The scan now also runs weekly, so the next such advisory is noticed without a push.
Security
Section titled “Security”-
oauthlib 4.0.1 (was 4.0.0; CVE-2026-49272, HIGH). 1.4.1 moved to 4.0.0 for this advisory, but its fix is in 4.0.1 (the advisory names
< 4.0.1; 4.0.0 closed a different one). python-fasthtml requires oauthlib for its OAuth sign-in, which this app doesn’t use. -
The runtime base image is refreshed (
python:3.14-slim-trixie, built 2026-11-08):apt3.0.4 (CVE-2026-109518, HIGH; the image runs no apt, but the scan reported it). The same image still shipszlib1g1:1.3.dfsg+really1.3.1-1+b1, which Debian has fixed (DSA-6613-1: CVE-2026-76844, CVE-2026-85091, both HIGH; heap overflows in zlib’sgz*file-writing routines, which nothing in the image calls) but no rebuilt base image carries yet; the Dockerfile runs no apt to pick it up. Those two are listed in a root.trivyignorewith an expiry of 2026-12-15, so the scan is green until the base image is rebuilt (the next release takes the digest bump) and red again on that date if it isn’t.
- A weekly image scan (
.github/workflows/image-scan.yml, development only): the same Trivy scan CI runs on every push, run againstmasterevery Monday (and from the Actions tab), so a CVE published against a base image or a locked dependency is noticed on the released image without waiting for the next push. See docs/DEVELOPMENT.md.
Changed
Section titled “Changed”- Dependencies: python-fasthtml 0.14.17 (was 0.14.13), starlette 1.10.0 (was
1.7.0), anyio 4.16.0 (was 4.15.1), pydantic 2.14.2 (was 2.14.1). The monitoring
profile’s images: Loki 3.7.9, Prometheus v3.15.1, Alloy v1.21.3, Grafana 13.3.0.
Development: playwright 1.64.1, pytest 9.2.0, pytest-mock 3.17.0, ruff 0.17.3 (the
lint’s rule set is unchanged), and the build stage’s uv image and CI’s
setup-uv(v10.3.2) pins. - Docs:
AGENTS.md, the guide for contributors and coding agents, is now a short core (about 21 KB, was 179 KB); the full facts and reasoning moved, unchanged, todocs/internals/(ten files, one per subsystem).
[1.4.1] - 2026-10-30
Section titled “[1.4.1] - 2026-10-30”A security update: oauthlib, which the web framework requires, moves past a HIGH
advisory. The v1.4.0 tag’s image scan failed on it, so upgrade from 1.3.1 straight to
1.4.1; 1.4.0’s notes below apply.
Security
Section titled “Security”- oauthlib 4.0.0 (was 3.3.1; CVE-2026-49272,
HIGH). python-fasthtml requires it for its OAuth sign-in, which this app doesn’t use;
the image scan of the
v1.4.0tag failed on it.
[1.4.0] - 2026-10-30
Section titled “[1.4.0] - 2026-10-30”The Jambonz SDK moves to 0.4.0, and its builder now writes and checks every verb: the verbs sent to Jambonz carry the SDK’s defaults and spelling, and a save refuses what the SDK rejects, on the component that holds it. Read the upgrade notes: a flow holding such a value keeps running as it was compiled before, until it is fixed.
Changed
Section titled “Changed”-
jambonz-python-sdk 0.4.0 (was 0.3.2), and every verb is now built and checked by its builder, so what reaches Jambonz is what the SDK (made for the commercial Jambonz) writes. The verbs change on the wire: they carry the SDK’s defaults (a gather’s
listenDuringPrompt: true, a Transfer target’smethod: "POST", a Record’ssampleRate: 8000, an AI Agent’scancelOnBargeIn/cancelOnResponseTimeout: false), a gather’s prompt is written{"verb": "say", …}, numbers are written as decimals (8.0), and an ElevenLabs AI Agent’sauth.api_keyis sent asapiKey. -
A save refuses a value the SDK rejects, on the component that holds it: an unknown field, a value outside a list of choices, text where a number belongs. The Issues row names the field and jumps to the component; it never repeats the value.
-
Compiled flows are rebuilt once after the upgrade (
COMPILED_FORMAT_VERSION4: the verbs above). It happens on each flow’s first call, automatically. -
A component card’s name has no tooltip. It is the card’s own text, and the Properties pane’s Label field shows it in full; the summary line under it keeps its tooltip with the full text.
Upgrade notes
Section titled “Upgrade notes”- A flow with a value the SDK now rejects keeps running as compiled before. Each flow is recompiled on its first call; one that no longer compiles is served from its previous compiled form, with an ERROR in the log naming the flow, until the component is fixed and the flow saved. Open each flow after upgrading: its Issues tab lists what to fix.
- The verbs sent to Jambonz change (see Changed). Place a test call through your flows’ Menus, User Inputs, Transfers and AI Agents before relying on it.
[1.3.1] - 2026-10-23
Section titled “[1.3.1] - 2026-10-23”A security update: the CA bundle the HTTP Request node verifies TLS against no longer
trusts emSign’s compromised intermediates. The v1.3.0 tag’s image scan failed on
that advisory, so upgrade from 1.2.0 straight to 1.3.1; 1.3.0’s notes below apply.
Security
Section titled “Security”- The CA bundle no longer trusts emSign’s compromised intermediates.
certifi2026.10.19 (was 2026.5.20; GHSA-6q48-6c7w-9gw2), the bundle the HTTP Request node verifies an API’s TLS certificate against. The advisory appeared after 1.3.0 was cut, and the image scan of thev1.3.0tag failed on it.
[1.3.0] - 2026-10-23
Section titled “[1.3.0] - 2026-10-23”Where callers go, on the dashboard; a load test for sizing how many webhooks run at
once, which now defaults to 100; pages that run no inline script; and browser tests for
the editor. Read the upgrade notes: an .env made from an earlier .env.example keeps
the old limit of 40, and a script a proxy injects into the pages is now refused.
-
Browser tests for the editor (development only).
tests/browser/drives the real app in Chromium with Playwright (sign-in, every main page, placing and editing components, Deploy, Issues, undo/redo, Simulate, the live Debug feed, the confirm dialog, the read-only account) and fails a test on any console error, failed request or Content-Security-Policy violation. Run withuv run pytest -m browser(left out of the default run); CI runs it in a newbrowserjob, and the pre-push hook where Chromium is installed. See docs/DEVELOPMENT.md, “The browser suite”. -
Where callers go, on the dashboard. Every routing decision is now an INFO line on the
app.routinglogger (waitingwhen a hook leaves the call waiting at a Menu, User Input, Transfer, queue or other component that waits for an answer,routedwhen that answer is routed or a Conditional or Date & Time picks its branch), naming the component (id, type, label), what happened (result: the option pressed,timeout,invalid, a transfer’sfailure, a queue’shangup, the rule that matched) and the branch the call took (outlet). Never the digits, speech or numbers themselves, and nothing from a dry run. The Grafana dashboard gets a Routing row drawn from them: Where callers go (decisions per component and outlet) and Hung up while waiting (calls that waited at a component and never came back), with a Flow box to narrow it to one flow. About one or two more log lines per webhook. See docs/OPERATIONS.md, “Reading the Routing panels”. -
A load test for sizing
WEBHOOK_MAX_CONCURRENCY.scripts/load_test.pyplays Jambonz at your own instance: whole calls (inbound hook, each continuation, status events) with Jambonz’s payloads, signature and customerData echo, arriving at a rate you set or ramp, against a bundled flow (scripts/load_test_flow.json,--import) whose HTTP lookup calls a built-in upstream you can slow down (--upstream-delay). It reports per step and hook kind (latency percentiles, shed hooks, late and failed answers), says whether the slots or the process’s CPU ran out first and how many slots the flow needs (Erlang B), and exits non-zero past--max-failed-pct. See docs/OPERATIONS.md, “Capacity and sizing”. -
Shed webhook answers carry
X-Jamhooks-Shed: 1, whatever their status, so a load test or a proxy log can count them without matchingCALLER_BUSY_MESSAGE(which may be localised, or empty).
Security
Section titled “Security”- The pages no longer allow inline script: the CSP’s
script-srcis'self'. It allowed'unsafe-inline'for the editor’s inlined code and a fewonclickhandlers, which left escaping as the only thing between a flow’s text and script running in the editor of whoever opened it. Now a browser runs only script files the app serves: the editor, the theme switch, the dashboard menus and the New / Import page are files under/static, and the data a page needs travels in<script type="application/json">blocks, which never execute. See docs/HARDENING.md.
Changed
Section titled “Changed”-
Script and stylesheet URLs carry a
?v=content hash, so after an upgrade a browser fetches the new editor instead of running a cached one against the new server. Something in front of the app that injects a script of its own (an analytics snippet, a banner) must now serve it as a file, or the browser refuses it. -
Compiled flows are rebuilt once after the upgrade (
COMPILED_FORMAT_VERSION3: a compiled component now carries its label, for the routing lines). It happens on each flow’s first call, automatically; nothing to do. -
WEBHOOK_MAX_CONCURRENCYdefaults to 100 (was 40, anyio’s own default, never measured). The load test showed what a slot spends its time on: waiting for an HTTP Request’s API. With a 2 s API, 40 slots turned callers away at about half the rate one core could serve, and 100 ran clean up to that limit. A waiting slot costs one idle thread, andMAX_HOOK_SECONDSstill bounds how long it waits.
-
The webhook-name fields checked nothing (on the New tab and when renaming in the editor’s Details pane). Their pattern was not a valid regular expression for current browsers, which dropped the check and logged a console error.
-
The dashboard’s Calls by flow table titles its count column Calls (it showed Grafana’s
Value #A).
Upgrade notes
Section titled “Upgrade notes”- An
.envmade from an earlier.env.examplekeepsWEBHOOK_MAX_CONCURRENCY=40: the line sets it, so the new default doesn’t reach you. Change it to100(or to whatscripts/load_test.pysays your flows need) and rundocker compose up -d. - A script injected into the pages by something in front of the app is now refused by the browser (the CSP allows only the app’s own files): an analytics snippet or a banner added by a proxy has to be served as a file instead. The app’s own pages are unaffected.
[1.2.0] - 2026-10-20
Section titled “[1.2.0] - 2026-10-20”Monitoring with logs kept for 30 days, test benches that exercise every component on a real call, and the project’s new name, Jamhooks. Read the upgrade notes before moving or re-cloning a checkout: Compose names the store volume after its directory.
- Monitoring, with logs kept for 30 days. A
monitoringcompose profile (Loki, Grafana Alloy, Prometheus and Grafana) keeps the app’s log lines forLOG_RETENTION(30 days by default) and then deletes them, probes/health, and comes with a dashboard (calls, webhook latency and outcomes, calls per flow,/health, the log with a call-sid search, the audit trail) and nine alert rules (app unreachable, webhooks shed, failing or slow, unknown flows, store unwritable, sign-in paused, an unsafe configuration at start, any other error).scripts/check_monitoring.pychecks a running stack; CI starts it on every change. See docs/OPERATIONS.md, “Monitoring”. - Node test benches. Seven example flows (
example/nodes/…, in the Load Example tab) that use every component between them: prompts and call audio, caller input, data tools, queues and conference, transfers and SMS, streaming and AI, subflow calls. Each is a keypad menu: a key runs one test, says which outlet it took and returns to the menu; destinations and services come from env vars set in the portal. See docs/FLOWS.md, “Trying every component on a real call”.
Changed
Section titled “Changed”- The project is now called Jamhooks. The repository moved to
github.com/jamhooks/jamhooks(the old URL redirects), the image isjamhooks:<version>and the editor’s page titles and sign-in page say Jamhooks. Flows, webhook URLs, settings and sign-ins are unchanged. Theivr-app-unreachablealert is now titled Jamhooks unreachable. - Docs: the README is now an overview and a quick start. The reference it held moved
to
docs/: building flows (FLOWS.md), how calls run (RUNTIME.md), the API (API.md), every setting (CONFIGURATION.md), production setup (DEPLOYMENT.md), security hardening (HARDENING.md) and development and releasing (DEVELOPMENT.md).
Upgrade notes
Section titled “Upgrade notes”- Keep your checkout’s directory, or name the project. Compose names the volumes
after the directory (
<directory>_storedataholds every flow), so a checkout moved to, or freshly cloned into, a directory calledjamhooksstarts with an empty store. Update an existing checkout in place (git remote set-url origin https://github.com/jamhooks/jamhooks.git, then upgrade as usual), or setCOMPOSE_PROJECT_NAMEin.envto the old directory’s name before the firstdocker compose upin the new place.docker volume lsshows which name holds yours. - The new release builds
jamhooks:<version>. Earlier releases’ images keep the name they were built under, and a rollback to one still finds it: the compose file at that release’s tag names it. - A browser that signed in before the upgrade is a stranger to the sign-in throttle again until its next successful sign-in (the known-browser cookie is signed under the new name). Only matters while sign-in is paused for strangers; sessions are unaffected.
.env.examplenow turns the profile on (COMPOSE_PROFILES=monitoring) and setsLOG_FORMAT=json, which the dashboard and alerts read. An existing.envis unchanged: add those two lines and aGRAFANA_ADMIN_PASSWORDto get the stack, then set up where alerts go in Grafana (Alerting → Contact points). Without them nothing changes; the app still runs alone.
[1.1.0] - 2026-10-15
Section titled “[1.1.0] - 2026-10-15”The Logger can also raise its line as a Jambonz alert. Nothing to do on upgrade: the option is off on every existing Logger, and stored flows run as before.
- The Logger can also raise a Jambonz alert. Tick Also send to Jambonz Alerts page and the line it logs is also raised as an application alert, listed against the call on the Jambonz portal’s Alerts page. Jambonz ignores what the call-status hook returns, so the save refuses it ticked in the Disconnect and Call Status handlers and anywhere they lead (a Logger that only logs stays allowed there), and in a queue’s wait subflow.
[1.0.1] - 2026-10-14
Section titled “[1.0.1] - 2026-10-14”Fixes from an audit of 1.0.0: one routing bug that callers hear, call state that went missing at the edges, webhook URLs that broke on a trailing slash, and operator docs that were wrong.
Upgrade notes
Section titled “Upgrade notes”- User Input with an
invalidbranch now routes valid answers correctly. A valid answer used to play theinvalidbranch first. It now takesdefault, or the next component. If a flow worked around this, review it. ALLOWED_HOSTSentries keep their port for the cross-site checks. A bare name means the standard port (https://nameorhttp://name), andname:8443means that port only. Only a proxy that rewritesHostand serves the editor on a non-standard port needs a change: list it asname:port. Otherwise browsers that don’t sendSec-Fetch-Siteget 403 on saves and the Debug pane won’t attach. An invalid port in an entry is now warned about and the entry ignored.- Don’t restart on an unhealthy
/health. If you followed the old advice (a cron or systemd restart,autoheal, a Kubernetes liveness probe on/health), remove it: a restart drops every live call and fixes none of the causes. Use/healthto alert a human. A liveness check, if you want one, is a TCP check on the port. See OPERATIONS.md. - A response that ends the call may now carry a
tagverb. It holds the call’s variables for the Disconnect and Call Status handlers. Tooling that asserts exact verb lists will see it.
- User Input sent valid answers down
invalidwhen that branch was wired. - The Disconnect and Call Status handlers saw stale variables. A variable set after the last menu or input step (say, the department chosen before a goodbye) never reached them; on a call that never suspended, none did.
- An Error handler that waited for input forgot this hook’s variables: the Start
values,
http_errorand HTTP Request mappings, so a “press 1 to retry” lost them. - A deleted flow variable came back with its default after the next menu or input step.
- Change Variable’s replace with an empty search text inserted the replacement between every character, and the value grew on every loop pass. It now changes nothing, and a blank search text is a save warning.
- JSON nested too deep to parse sent the call to the Error handler from a JSON
Parser. It now sets
{{json_error}}, and an HTTP Request sets{{http_error}}with a clean message. - A queue’s wait hook answered say + hangup when shed or unrenderable, which Jambonz refuses: the queued caller sat in silence, under load. It now answers with nothing to play.
- A trailing
/on a webhook URL broke every call (“unavailable”), hid the env vars from the portal, and sent/callstatus/and/subflows/<name>/to the inbound route. Every hook now answers on its URL with one trailing slash. - The image shipped without
examples/, so Load Example was empty in production. - A deeply nested JSON body to
/api/was a 500. It is now a 400.
Security
Section titled “Security”- A page on another port of a listed
ALLOWED_HOSTSname passed the CSRF and Debug-socket origin checks, so it could delete flows or watch live calls. - Dynamic responses are
Cache-Control: no-store, so a browser can’t keep the admin’s editor page (obscure defaults in clear) past a sign-out on a shared machine.
Documentation
Section titled “Documentation”/healthdocs. A full disk is a 503, and the probe is for alerting only.- The nginx example passes
nginx -ton Ubuntu 24.04 and Debian 12 (listen 443 ssl http2;). - README corrections: the handler JSON keys are
error,disconnectandcallstatus; the Debug pane section is rewritten; backups stop the app first; the proxy-address steps run in an order that works; webhook basic auth goes on both webhooks.
[1.0.0] - 2026-10-13
Section titled “[1.0.0] - 2026-10-13”The first tagged release. It gathers two production-readiness passes: the second checked the runtime against what a real Jambonz sends (its feature-server source and the SDK’s callback schemas) rather than against this app’s own assumptions, and fixed what didn’t match.
Upgrade notes
Section titled “Upgrade notes”Read these before deploying this release over an existing one.
-
Configure the call status webhook. A Jambonz application has two webhooks; point the call status webhook at
…/webhooks/<flow>/callstatus. The Disconnect and Call Status handlers run only from it; Jambonz has no error or disconnect hook. Remove any status hook pointed at/erroror/disconnect. -
A hook answers within 8 s.
MAX_HOOK_SECONDSdefaults to 8 (was 30), because Jambonz waits about 10 s for an answer and doesn’t retry. An HTTP Request gets at most what is left of the hook’s budget, and the Error handler runs on the remainder. A flow whose hooks legitimately took longer now ends in its Error handler; raising the setting above ~9 s is pointless. -
Components after a Subflow node now run when the subflow ends; they were dead before. Review flows that left anything there.
-
Saves are stricter. Deployed flows keep running from their last compiled artifact, with an
ERRORnaming them, until they are fixed and saved. Refused now: a cycle through a Subflow, or through a Loop entered from outside its body; Send SMS in the Disconnect or Call Status handler; a variable namedreason,queue_result,dequeue_result,refer_statusorfinal_referred_call_status, or any name starting with__(the runtime’s own); Call Control or Send SMS reached from the Disconnect or Call Status handler through a Subflow component or a Connector; a queue’s wait subflow that plays anything but play/say/pause/tag/leave; a template condition that doesn’t parse; an unknown Date/Time timezone; an AI Agent with an unsupported vendor or without its vendor’s required keys. -
Running flows behave differently where they were wrong:
- template conditions with an operator evaluate as written (
{{x}} == 'y'was always true); - a numeric comparison on an unset or empty variable is no longer satisfied (it read as 0): initialise counters before testing them;
- a blank Date/Time timezone is UTC (it was the host’s local time), and an overnight window covers the morning after the day it starts;
- Play Prompt with loop 0 repeats until interrupted, and a voice, language or gender set without a vendor is now used (with the call’s vendor) instead of ignored;
- a successful Blind Transfer ends the flow: the components after it run only when it failed;
- a Take From Queue
bridgedbranch routes ascomplete, and an Enter Queuetimeoutor Take From Queueerrorbranch is flagged as one that can never be taken; - Voice Input and Transcribe left blank inherit the application’s speech settings; existing components keep the google/en-US they were created with until cleared;
- an AI Agent with a system prompt and key but no model options is moved into its vendor’s template; any other old configuration fails to save, with directions;
- a variable whose name starts with
__no longer survives a wait for input: rename it.
- template conditions with an operator evaluate as written (
-
Compiled artifacts are rebuilt on first use (format 2). Nothing to do.
-
Reverse proxy: if you copied the nginx example, change it to
proxy_set_header X-Forwarded-For $remote_addr;and setFORWARDED_ALLOW_IPSto the proxy’s address, never*. -
Obscure env-var defaults stay in the app: exports and version downloads drop them (importing one leaves the default empty), the read-only account sees
••••••••, and Simulate shows[redacted]. Secrets belong in the Jambonz portal. -
Docker: the image is now tagged with its release version; the old
<project>-app:latestis left alone as your rollback target. It runs Python 3.14 on Debian 13 with a read-only root filesystem. Build with--build-arg APP_REVISION="$(git rev-parse HEAD)"so it can report its revision. Back up withscripts/backup.shand restore withscripts/restore.sh; the old copy-paste commands couldn’t read the session key. -
Store files are owner-only (0600), tightened on their next write.
-
Logs: timestamps are ISO 8601 UTC with milliseconds (
…Z); uvicorn’s own lines now followLOG_FORMATandLOG_LEVELand go to stderr; control characters are escaped (\x0a)./healthcan answer 503 on a full volume, and its body carriesversion. -
SSRF guard (
HTTP_REQUEST_ALLOW_PRIVATE=false): 100.64.0.0/10 is refused, and a public host reached through NAT64 (64:ff9b::/96) is allowed. -
New warnings (they never block a save): an obscure env var with a default; a Send SMS recipient the caller controls; a variable named like a field Jambonz sends; a blank Date/Time timezone; a literal API key in an AI Agent.
-
Everyone signs in once. Sessions now carry a sign-in time and a session id; a cookie from before the upgrade has neither and is refused.
-
Every compiled flow is rebuilt on its first call (a new format stamp). A flow the stricter validation below now refuses keeps answering from its previous compiled artifact, with an
ERRORnaming it, until it is fixed and saved. Check the log after the upgrade. -
Saves are stricter. A save is refused (422 with issues) when the flow would not compile (including the Jambonz verb-schema checks the save used to skip) and when it uses a reserved variable name (
digits,speech,queueResult,dial_call_status, …) or a component id / subflow name outside[A-Za-z0-9_-]. -
HTTP Request URLs are percent-encoded. Values interpolated into the path, query or fragment are encoded; a placeholder that starts the URL or sits in the host part is not. Write
{{var|raw}}where a mid-URL value must go in as-is. Where a URL starts with a base placeholder, its value decides where the host part ends: with no path in it (https://api.example.com),{{BASE}}{{path}}inserts{{path}}as-is; with one, what follows is encoded. A save now warns about a placeholder that is a whole query component (?{{qs}}: a pre-builta=1&b=2is sent encoded as one value) and about a placeholder in a Change Variable regex (matched literally now). Check the Issues tab of flows that use either. -
Values that used to be ignored now apply (see the compose fix below), and an invalid number (negative,
nan, a typo) now falls back to its default with a warning: a negativeMAX_HOOK_SECONDSno longer disables the budget, and aWEBHOOK_MAX_CONCURRENCYbelow 1 becomes 40, not 1. -
An editor without a login answers only on loopback names and the
BASE_WEBHOOK_URLhost. Reached another way (an IP, an internal name)? SetALLOWED_HOSTS. -
/api/writes with a body must beapplication/json(anything else is a 415). -
Compose publishes the port on
127.0.0.1only. If Jambonz (or a proxy on another host) reaches port 5001 directly, setAPP_PUBLISH=5001beforeup -d, or every webhook stops arriving. The compose file now needs Docker Compose 2.24 or later (env_filewithrequired: false). -
HTTP_REQUEST_TIMEOUTis a total deadline for the whole request, body included, not a per-read timeout; an API that is slow but steady may need a higher value. -
Call state is capped at
MAX_CALL_STATE_BYTES(64 KiB). A flow that stores a large HTTP response in a variable now runs its Error handler at the next wait for input, rather than having Jambonz’s next webhook refused; map the fields you need.
- Subflows call and return. When a subflow ends (right away or after menus and transfers), the call continues after the Subflow node. One subflow can be used from many places, calls nest, and recursion is refused at save.
- Template conditions are expressions:
==!=<><=>=contains,and/or/notand parentheses, parsed before any value is filled in: caller input can’t become syntax. A template that doesn’t parse is reported at save. - AI Agent starter templates for every vendor Jambonz’s
llmverb supports (openai, microsoft, google, deepgram, voiceagent, ultravox, elevenlabs), in its own editor panel. Each vendor’s required keys are checked at save, and the API key’s env var is declared obscure automatically. - Per-prompt voice (vendor, language, voice) on Menu, User Input and Voice Input.
- An
invalidoutlet on User Input, for fewer digits than its minimum. CALLER_UNAVAILABLE_MESSAGEandCALLER_BUSY_MESSAGE: what a caller hears when the flow can’t run or the app is busy (empty hangs up without a word).- Version reporting:
/healthand a startup line carry the version and the build’sAPP_REVISION; the image carries OCI labels. scripts/backup.shandscripts/restore.sh, run by CI against the built image.- CI on
v*tags builds, scans and smoke-tests the image and checks thatpyproject.toml,docker-compose.ymland this changelog name the same version (nothing is published). - A versioned pre-push hook:
git config core.hooksPath scripts/git-hooks. - The release check covers
uv.lock: a test and the tag’s CI job fail unlesspyproject.toml, the compose image tag, itsAPP_VERSIONanduv.lockname the same version. - Contract tests built from the Jambonz SDK’s callback schemas, so the runtime is checked against what Jambonz sends, not against its own assumptions.
- Save warnings: an obscure env var with a default; a Send SMS recipient the caller controls (SMS pumping); a variable named like a field Jambonz sends; a blank Date/Time timezone.
- Date/Time components take the browser’s timezone when they are added.
- CI: a container smoke test: the built image is started with login and a webhook
secret, and must answer
/healthand/login, log noSECURITY:line, and stop cleanly onSIGTERM. - CI: a Trivy scan of the image, failing on fixable HIGH/CRITICAL vulnerabilities.
- CI: Dependabot (weekly grouped updates for the GitHub Actions, the base images and the Python lock).
- CI:
tests/test_deploy_config.py(.envreaches the container, compose pins nothing beyond its allowed set, every setting the app reads is documented in.env.example, and the shutdown timeouts nest). - Docs:
docs/OPERATIONS.md(Caddy and nginx examples, backup and restore, upgrade and rollback, secret rotation, and why it is one instance per store). - Docs:
docs/PRIVACY.md(what the app stores and logs about callers and editor users). - Docs: a Releasing section in the README, and this changelog.
- Audit trail: one
app.auditline per change to a flow (create, save, rename, restore, import, duplicate, delete) naming the account or gateway identity, the flow and its version; every version snapshot records its author, shown in the history. - A completion line per webhook: status,
duration_ms, verb count and outcome flags (shed,not_found,node_error,error_handler,budget_exceeded,render_failed); top-level keys underLOG_FORMAT=json, and the source for metrics. - Settings:
MAX_CALL_STATE_BYTES(64 KiB),ALLOWED_HOSTS,SESSION_MAX_LIFETIME(12 h),TRUSTED_USER_HEADER_SECRET. CONFIG:startup errors for a missing or loopbackBASE_WEBHOOK_URLon a public bind, and warnings for every setting that is invalid and fell back to its default.{{var|raw}}: opt a value out of URL encoding (and of regex escaping).- A compiler warning when a Transfer or Blind Transfer target is built from caller
input (
{{digits}},{{from}}, a gathered variable…). Check it with a Conditional first, or it is a toll-fraud path.
Changed
Section titled “Changed”MAX_HOOK_SECONDS30 → 8, HTTP Request deadlines clamped to what is left of the hook’s budget, and the Error handler run on the remainder: every hook answers inside Jambonz’s ~10 s wait.- The Disconnect handler runs from the call status webhook, once, on the call’s final status; the Call Status handler runs only for the leg the flow drives. The Details page lists the two webhooks Jambonz has, and which webhook auth is on.
- Loops, Connectors and Exit: a Loop entered from outside its body restarts its count; a Connector into another tree abandons any subflow calls in progress; Exit Call Flow inside a subflow ends the call.
- A compare condition’s value may be
{{var}}. - Speech recognition left blank inherits the application’s settings (it used to force google/en-US).
- A successful Blind Transfer ends the flow.
OPTIONS(env-var discovery) is exempt from webhook basic auth (Jambonz sends no credentials on it) and answers 204 for a flow without env vars./healthproves a real write; logs are one format end to end, with UTC millisecond timestamps.- Docker: Python 3.14 on Debian 13, a read-only root filesystem, root-owned source
byte-compiled at build time, an allowlist build context and one image tag per release. CI: Python 3.11–3.14 on
ubuntu-24.04,uv --locked, ruff’s rules selected explicitly; dependency floors raised to what the code relies on, andstarlette,anyioandhttpcoredeclared. - Deployment: compose publishes the port on
127.0.0.1only; a reverse proxy on the same host still reaches it. SetAPP_PUBLISH=5001(or0.0.0.0:5001) to publish it on every interface as before. - Deployment: container logs are capped at 5 × 10 MB (they carry call sids and the addresses of failed sign-ins).
- Deployment: both Dockerfile base images are pinned by digest, and pip, setuptools and wheel are removed from the runtime image (unused there; setuptools carried vulnerable vendored packages).
- CI: every action is pinned to a commit SHA and moved to its current major
(Node 24):
actions/checkoutv7,astral-sh/setup-uvv10,actions/setup-nodev7. Workflows run with a read-only token and don’t persist checkout credentials. - UI assets: Font Awesome 7.3.1 (was 6.5.1) and htmx 2.0.11 (was 1.9.12). Font
Awesome 7 ships woff2 webfonts only, so the old
.ttffiles are deleted fromvendor/on the first start after the upgrade, and icons are fixed-width by default (a few are a little wider). htmx 4 is out but npm still tags itnext, and FastHTML targets htmx 2.
Security
Section titled “Security”- The documented reverse-proxy setup let a client choose its own address, escaping
the per-address rate limit and sign-in lockout. nginx now overwrites
X-Forwarded-For,FORWARDED_ALLOW_IPSnames the proxy, and both per-address maps are capped. - Obscure env-var defaults are masked for the read-only account and dropped from exports, version downloads and Simulate output.
- Env-var values are read only from a call’s first hook, and with webhook auth off the startup error now says that anyone can set them, and so steer where an HTTP Request sends its secrets.
- SSRF guard: every non-global address is refused, including 100.64.0.0/10 (cloud metadata, Tailscale); a NAT64 address is judged by the IPv4 address it reaches.
- Log lines can’t be forged with newlines or control characters, in either format.
- The runtime’s own state can’t be forged: names starting with
__are reserved, a hook body can’t set one, and a call-stack entry that isn’t a Subflow node of the deployed flow is dropped; with webhook auth off, a forged one could resume a call wherever it liked. - Caller-facing fallback messages no longer reveal internals (“Flow not found or not compiled.”).
- Owner-only storage: store files 0600 and directories 0700, backups 0600; the container’s root filesystem is read-only and its source root-owned.
- Closed an arbitrary file read. FastHTML’s catch-all static route served any file on
the host with a common extension (
.txt,.yml,.csv,.zip, …) through..in the path, to anyone when the editor had no login, to any signed-in account otherwise. The route is removed; assets are served by the/staticmounts. - Caller data and secrets kept out of the logs. The HTTP client’s per-request INFO
line (full URL, query string included: the caller’s number, the API key) is off,
and an HTTP Request failure logs the host it went to and the path as the author wrote
it (
/accounts/{{digits}}): no interpolated caller input, no query string. - Secret (obscure) environment variables no longer appear as defaults in the
OPTIONSschema answer and are masked in the Debug pane. - Caller input can’t reshape requests: URL values are percent-encoded (above), and a Change Variable regex escapes interpolated values instead of compiling them.
- CSRF: an
Origin: null(sandboxed frame) no longer passes the origin check, and a cross-sitetext/plainbody can no longer reach the JSON API. - DNS rebinding: see
ALLOWED_HOSTS. The Debug socket also checksOrigin(close code 4400). - Trusted-header mode can require a shared secret from the gateway
(
TRUSTED_USER_HEADER_SECRET), and a startup warning says when it doesn’t. - Sessions: a 12-hour absolute lifetime, and signing out revokes the session on the
server, not just in the browser.
.sesskeyis created0600. - Less leaked:
/healthno longer returns the store path on failure; a failed sign-in no longer logs the typed username. - Webhooks: a malformed signature is a 403, not a 500;
OPTIONSruns in its own two-slot lane so a flood of them can’t take every call slot. - Front-end assets are pinned to exact versions and verified by sha256. Tailwind
was pinned only to its major (
@4, whatever the CDN served that day); it is now 4.3.3, fetched as the npm package’s own file rather than jsDelivr’s on-the-fly re-minification. Every file the app vendors (Tailwind, HTMX, Font Awesome’s CSS and each of its webfonts) has a sha256 inapp/ui/assets.py, checked before anything is written tovendor/. A mismatch is a failed download (fatal on a first start, a warning that keeps the old files on an upgrade), and nothing from a failed run is written.scripts/vendor_assets.py --checkre-hashes what is on disk and reports amodifiedfile;--print-hashesproduces the pins when bumping a version. - Dependencies: bumped the locked packages the image scan flagged: anyio 4.15.1
(CRITICAL, CVE-2026-63374), starlette 1.7.0 (CVE-2026-54283), python-multipart 0.0.32
(CVE-2026-53539) and aiohttp 3.14.5 (CVE-2026-69244); typing-extensions and yarl move
with them. On the new Starlette an over-long body sent without a
Content-Lengthgot a500instead of a413; the size cap now answers413whatever shape the overflow comes back to it in.
- Queue outcomes never routed. Enter Queue and Take From Queue read
queueResult, a field Jambonz never sends (it sendsqueue_resultanddequeue_result), so every outcome tooktimeout, a finished agent conversation included. - The Disconnect handler never ran, and Send SMS in Disconnect or Call Status never sent: Jambonz has no disconnect hook and ignores the answer to a status hook.
- The Call Status handler ran for every leg, so a “post the call record” HTTP node fired several times per call.
- The AI Agent sent an
llmverb that no vendor accepts, and the call dropped. - Template conditions written as
{{x}} == 'y'were always true; an empty input passed “less than”; a compare couldn’t test one variable against another. - A Subflow never returned; a cycle through a subflow or loop compiled cleanly, and the iteration cap then played thousands of prompts; a Loop left through a branch read as exhausted when entered again.
- One slow API dropped the call before the Error handler could answer.
- The Jambonz portal rejected the env-var schema, and it was unreachable behind webhook basic auth.
- A call created over the REST API lost its customerData at the first gather.
- Misrouted answers: a speech-recognizer error was a silent timeout, a low-confidence transcript a match, User Input below its minimum an answer, and a dial ending while ringing a failure.
- Date/Time: overnight windows were checked against the wrong day; an unknown timezone fell back to the host’s local time.
- Play Prompt: loop 0 played once; the style prompt never reached anything that reads it. Call Settings with only a voice sent a synthesizer without a vendor, which Jambonz refuses, a blank language or voice cleared the call’s, and it switched off the application’s TTS fallback.
- A prompt with its own voice or recognizer, or a Call Settings, switched the call to the vendor’s unlabelled speech credential. The application’s credential labels are now read from the call’s first hook and kept on every synthesizer and recognizer that uses the call’s vendor.
- A queue’s wait subflow could silence the hold music; a successful Blind Transfer still ran its fallback components.
- The documented backup failed every time (it couldn’t read the session key) and left the app stopped.
- A save on a full disk answered 500 though it had landed, with no audit line, and
/healthsaid ok while saves failed. LOG_FORMAT=jsonwasn’t all JSON; the session-key warning fired on read-only volumes; directory changes and deletes weren’t durable.- Docs that no longer matched the code: the hook model, trusted-header auth, the audit
trail,
/health, the masked-header list. - Deployment: compose silently ignored most of
.env. It listed settings one by one underenvironment:, so a dozen of them (among othersMAX_HOOK_SECONDS,HTTP_REQUEST_ALLOW_PRIVATE,CALL_TRACE_ENABLED,TRUSTED_USER_HEADER,LOG_LEVEL,RATE_LIMIT_PER_MINUTE) never reached the container. The whole.envnow goes in throughenv_file(optional, so the quick start still runs without one); onlySTORE_DIR,DEBUG,UVICORN_WORKERS,APP_HOSTandAPP_PORTare pinned. Check your.env: values that used to be ignored now take effect. - Deployment: a restart cut off running webhooks. uvicorn now drains for up to
GRACEFUL_SHUTDOWN_SECONDS(default 40, longer thanMAX_HOOK_SECONDS) afterSIGTERM, and compose waits 45 s (stop_grace_period) before it kills the container (Docker’s default was 10 s). - Docs: removed the claim that extra replicas can serve webhooks from a copy of the store: a copy is a separate, writable installation. One instance per store; high availability is a future platform concern.
- Docs:
docs/PLATFORM-HANDOFF.mdanddocs/ARCHITECTURE-DIRECTION.mdno longer describe groups,/webhooks/{group}/{flow}or basic auth for the editor. - A save could take a flow off the air, two ways: it deleted the compiled artifact before recompiling outside the lock (a call in that gap hung up), and its check skipped the verb-schema validation the compile then failed. Every write now compiles first and replaces the artifact atomically in the same locked write.
- The compiled artifact heals. Missing, corrupt or from another release, it is rebuilt from the flow on the next call; a corrupt one used to be a 500 on every call.
- One bad file no longer breaks the rest: an invalid flow document is skipped (and
logged) in the dashboard and
GET /api/flows, an invalid snapshot no longer blocks saves or the history, and a short write on a full disk is completed rather than renamed over the good file. - A webhook could answer 500 and drop the call on a
NaN/Infinity(from an API response or a number env var); responses are now rendered where a failure still becomes a 200 with a hangup. - Large call state dropped the call: variables near 1 MiB made Jambonz’s next
webhook a 413. Over
MAX_CALL_STATE_BYTESthe Error handler runs instead. - HTTP Request could hold a call indefinitely:
HTTP_REQUEST_TIMEOUTwas per read, so a trickling upstream never timed out, and DNS had no bound with the SSRF guard off. It is now a total deadline, DNS included. - HTTP Request failed in bursts: more than four requests resolving a hostname at once failed with “all 4 DNS lookup slots are still occupied”, with the SSRF guard on before this release, and in every mode once DNS moved onto the bounded resolver. Only lookups abandoned to a hung resolver are capped now; every other lookup gets a thread.
- A base URL in a placeholder broke the request: with URL encoding,
{{env_vars.BASE}}{{path}}encoded the path into the host (https://api.example.com%2Fv1%2Fcustomers). Where a URL’s host part ends is now decided with the base’s value in place, for the request and its log line alike, and a save warns about the two shapes the encoding changes (see Upgrade notes). - A variable name that wasn’t text made a save a 500: a number where a name belongs
(
"variable_name": 7, a Loop counter, a mapping’svariable) or a non-list mapping in an imported flow made save, validate and import answer 500, and the webhook’s rebuild of the flow fail. Names are read as text now; a Change Variableoperationthat isn’t one is a 422 (“unknown operation”) instead of a 500. - Load shedding didn’t shed: a burst saw free slots, then queued. Slots are now taken before the hook is admitted.
- A field of the wrong type was a 500 on save, import and validate (a list as a Connector target, a number as an SMS recipient, …); the compiler now refuses the flow with an issue instead of raising.
- Unknown webhook names cost a full store scan each; misses are cached briefly.
- Saves and Simulate blocked every webhook while they ran; they now run off the event loop.
- Resumes broke for a subflow name or component id with
/,?,#or a space, and a variable named like a gather result (digits…) made a later timeout read the stale value as an answer. Both are now refused at save. - The JSON Parser node had no icon:
fa-brackets-curlyis a Font Awesome Pro icon, so the palette and its cards showed a blank. It now usesfa-code.