@falai/agent 4.0.0-alpha.4 → 4.0.0-alpha.6

package/dist/cjs/utils/template.d.ts

@@ -5,6 +5,14 @@
  * per-turn context) and `input` (the run's trigger payload). A path that
  * resolves to nothing keeps its placeholder, so a typo stays visible instead
  * of vanishing into an empty string.
+ *
+ * A path the host answered with nothing is a different case: it knows the
+ * field and knows it is blank. Then the placeholder goes and `tidy` closes the
+ * gap it left, so "Ola {{context.lead.name}}, tudo bem?" sends "Ola, tudo bem?"
+ * and never "Ola , tudo bem?". Two things count as blank: an empty string, and
+ * a path that walks THROUGH a null — `context.lead` being `null` means there
+ * is no lead, so "the lead's name" is blank, not mistyped. A null at the end of
+ * a path is still unknown: a field that collected nothing keeps its braces.
  */
 export interface TemplateScope {
     data?: unknown;

package/dist/cjs/utils/template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../../src/utils/template.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAID,wBAAgB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,MAAM,CAKrE;AAED,wFAAwF;AACxF,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,aAAa,GAAG,CAAC,CAS/D"}
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../../src/utils/template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAOD,wBAAgB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,MAAM,CAcrE;AAiBD,wFAAwF;AACxF,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,aAAa,GAAG,CAAC,CAS/D"}

package/dist/cjs/utils/template.js

@@ -6,16 +6,51 @@
  * per-turn context) and `input` (the run's trigger payload). A path that
  * resolves to nothing keeps its placeholder, so a typo stays visible instead
  * of vanishing into an empty string.
+ *
+ * A path the host answered with nothing is a different case: it knows the
+ * field and knows it is blank. Then the placeholder goes and `tidy` closes the
+ * gap it left, so "Ola {{context.lead.name}}, tudo bem?" sends "Ola, tudo bem?"
+ * and never "Ola , tudo bem?". Two things count as blank: an empty string, and
+ * a path that walks THROUGH a null — `context.lead` being `null` means there
+ * is no lead, so "the lead's name" is blank, not mistyped. A null at the end of
+ * a path is still unknown: a field that collected nothing keeps its braces.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.render = render;
 exports.renderDeep = renderDeep;
 const PLACEHOLDER = /\{\{\s*([^}\s]+)\s*\}\}/g;
+/** The path ran into a `null` on its way down: the container the host named is absent. */
+const ABSENT = Symbol("absent");
 function render(template, scope) {
-    return template.replace(PLACEHOLDER, (match, path) => {
+    let emptied = false;
+    const out = template.replace(PLACEHOLDER, (match, path) => {
         const value = lookup(scope, path.split("."));
-        return value === undefined || value === null ? match : stringify(value);
+        if (value === ABSENT) {
+            emptied = true;
+            return "";
+        }
+        if (value === undefined || value === null)
+            return match;
+        const text = stringify(value);
+        if (text === "")
+            emptied = true;
+        return text;
     });
+    return emptied ? tidy(out) : out;
+}
+/**
+ * Close the hole an empty value leaves: a doubled space, a space before
+ * punctuation, a space at the end of a line.
+ *
+ * Deliberately narrow. It only runs on a string where something substituted to
+ * "", and it only collapses a run of spaces that follows a visible character,
+ * so indentation in a markdown list survives.
+ */
+function tidy(text) {
+    return text
+        .replace(/(?<=\S)[ \t]{2,}/g, " ")
+        .replace(/ +([,.;:!?\u2026])/g, "$1")
+        .replace(/[ \t]+$/gm, "");
 }
 /** `render` over every string inside a value, recursively. Non-strings pass through. */
 function renderDeep(value, scope) {
@@ -31,7 +66,9 @@ function renderDeep(value, scope) {
 function lookup(root, keys) {
     let current = root;
     for (const key of keys) {
-        if (current === null || typeof current !== "object")
+        if (current === null)
+            return ABSENT;
+        if (typeof current !== "object")
             return undefined;
         current = current[key];
     }

package/dist/cjs/utils/template.js.map

@@ -1 +1 @@
-{"version":3,"file":"template.js","sourceRoot":"","sources":["../../../src/utils/template.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAUH,wBAKC;AAGD,gCASC;AAnBD,MAAM,WAAW,GAAG,0BAA0B,CAAC;AAE/C,SAAgB,MAAM,CAAC,QAAgB,EAAE,KAAoB;IAC3D,OAAO,QAAQ,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,IAAY,EAAE,EAAE;QAC3D,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QAC7C,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC1E,CAAC,CAAC,CAAC;AACL,CAAC;AAED,wFAAwF;AACxF,SAAgB,UAAU,CAAI,KAAQ,EAAE,KAAoB;IAC1D,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,KAAK,EAAE,KAAK,CAAM,CAAC;IAChE,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAa,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,CAAM,CAAC;IAC5F,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAC5D,CAAC;IACT,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,MAAM,CAAC,IAAa,EAAE,IAAc;IAC3C,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACtE,OAAO,GAAI,OAAmC,CAAC,GAAG,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IAClF,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC"}
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../../../src/utils/template.ts"],"names":[],"mappings":"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"}

package/dist/utils/template.d.ts

@@ -5,6 +5,14 @@
  * per-turn context) and `input` (the run's trigger payload). A path that
  * resolves to nothing keeps its placeholder, so a typo stays visible instead
  * of vanishing into an empty string.
+ *
+ * A path the host answered with nothing is a different case: it knows the
+ * field and knows it is blank. Then the placeholder goes and `tidy` closes the
+ * gap it left, so "Ola {{context.lead.name}}, tudo bem?" sends "Ola, tudo bem?"
+ * and never "Ola , tudo bem?". Two things count as blank: an empty string, and
+ * a path that walks THROUGH a null — `context.lead` being `null` means there
+ * is no lead, so "the lead's name" is blank, not mistyped. A null at the end of
+ * a path is still unknown: a field that collected nothing keeps its braces.
  */
 export interface TemplateScope {
     data?: unknown;

package/dist/utils/template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/utils/template.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAID,wBAAgB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,MAAM,CAKrE;AAED,wFAAwF;AACxF,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,aAAa,GAAG,CAAC,CAS/D"}
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/utils/template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAOD,wBAAgB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,MAAM,CAcrE;AAiBD,wFAAwF;AACxF,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,aAAa,GAAG,CAAC,CAS/D"}

package/dist/utils/template.js

@@ -5,13 +5,48 @@
  * per-turn context) and `input` (the run's trigger payload). A path that
  * resolves to nothing keeps its placeholder, so a typo stays visible instead
  * of vanishing into an empty string.
+ *
+ * A path the host answered with nothing is a different case: it knows the
+ * field and knows it is blank. Then the placeholder goes and `tidy` closes the
+ * gap it left, so "Ola {{context.lead.name}}, tudo bem?" sends "Ola, tudo bem?"
+ * and never "Ola , tudo bem?". Two things count as blank: an empty string, and
+ * a path that walks THROUGH a null — `context.lead` being `null` means there
+ * is no lead, so "the lead's name" is blank, not mistyped. A null at the end of
+ * a path is still unknown: a field that collected nothing keeps its braces.
  */
 const PLACEHOLDER = /\{\{\s*([^}\s]+)\s*\}\}/g;
+/** The path ran into a `null` on its way down: the container the host named is absent. */
+const ABSENT = Symbol("absent");
 export function render(template, scope) {
-    return template.replace(PLACEHOLDER, (match, path) => {
+    let emptied = false;
+    const out = template.replace(PLACEHOLDER, (match, path) => {
         const value = lookup(scope, path.split("."));
-        return value === undefined || value === null ? match : stringify(value);
+        if (value === ABSENT) {
+            emptied = true;
+            return "";
+        }
+        if (value === undefined || value === null)
+            return match;
+        const text = stringify(value);
+        if (text === "")
+            emptied = true;
+        return text;
     });
+    return emptied ? tidy(out) : out;
+}
+/**
+ * Close the hole an empty value leaves: a doubled space, a space before
+ * punctuation, a space at the end of a line.
+ *
+ * Deliberately narrow. It only runs on a string where something substituted to
+ * "", and it only collapses a run of spaces that follows a visible character,
+ * so indentation in a markdown list survives.
+ */
+function tidy(text) {
+    return text
+        .replace(/(?<=\S)[ \t]{2,}/g, " ")
+        .replace(/ +([,.;:!?\u2026])/g, "$1")
+        .replace(/[ \t]+$/gm, "");
 }
 /** `render` over every string inside a value, recursively. Non-strings pass through. */
 export function renderDeep(value, scope) {
@@ -27,7 +62,9 @@ export function renderDeep(value, scope) {
 function lookup(root, keys) {
     let current = root;
     for (const key of keys) {
-        if (current === null || typeof current !== "object")
+        if (current === null)
+            return ABSENT;
+        if (typeof current !== "object")
             return undefined;
         current = current[key];
     }

package/dist/utils/template.js.map

@@ -1 +1 @@
-{"version":3,"file":"template.js","sourceRoot":"","sources":["../../src/utils/template.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,MAAM,WAAW,GAAG,0BAA0B,CAAC;AAE/C,MAAM,UAAU,MAAM,CAAC,QAAgB,EAAE,KAAoB;IAC3D,OAAO,QAAQ,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,IAAY,EAAE,EAAE;QAC3D,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QAC7C,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC1E,CAAC,CAAC,CAAC;AACL,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,UAAU,CAAI,KAAQ,EAAE,KAAoB;IAC1D,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,KAAK,EAAE,KAAK,CAAM,CAAC;IAChE,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAa,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,CAAM,CAAC;IAC5F,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAC5D,CAAC;IACT,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,MAAM,CAAC,IAAa,EAAE,IAAc;IAC3C,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACtE,OAAO,GAAI,OAAmC,CAAC,GAAG,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IAClF,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC"}
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../../src/utils/template.ts"],"names":[],"mappings":"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"}

package/docs/guides/actions-and-events.md

@@ -53,7 +53,7 @@ A `do` step fills the parameters with `with`. When the agent is built, `validate
 - a value has the wrong type; nothing is coerced, so `"3"` is not a number. A template such as `"{{data.cep}}"` is a string, so templates can only fill string parameters (and the items of a string array);
 - `with` names a parameter the action does not have.
 
-Templates in `with` are rendered right before `run` is called, against `data` (collected fields), `context` (this turn's host context) and `input` (the run's input). A path that resolves to nothing keeps its `{{...}}`, so a typo stays visible.
+Templates in `with` are rendered right before `run` is called, against `data` (collected fields), `context` (this turn's host context) and `input` (the run's input). An unknown path keeps its `{{...}}`, so a typo stays visible. A blank one drops out, and the space or comma it left behind goes with it — an empty string, or a path that walks through a `null` such as `{{context.lead.name}}` when there is no lead.
 
 ## What `run` sees
 

package/docs/migration/v3-to-v4.md

@@ -410,13 +410,14 @@ Host actions, events and conditions are registered once on the agent and referen
 | `agent.dispatch`, `pendingDirective`, `Directive`, `flow.merge`, `flow.validate` | `then` / `else` on steps |
 | `Flow` class, `Step` class, `flow` namespace, `FlowOptions`, `StepOptions` | plain objects: `Flow`, `Step` |
 | `title`, `when`, `if`, `reentrant`, `requiredFields`, `optionalFields`, `onComplete`, flow `hooks` | `id` + `name`, `on[]`, `repeat`, `clearOnStart`, `onEnd`, `while` |
-| `requires`, `skip`, `auto`, `reply`, step `hooks`, `prepare`, `finalize` | known-field skipping, `maxAsks`, `do`, `if`, `wait`, `say` |
+| `skip`, `auto`, `reply`, step `hooks`, `prepare`, `finalize` | known-field skipping, `maxAsks`, `do`, `wait`, `say` |
+| `requires` | an `if` step: `{ if: { known: [...] }, then: '<step>', else: 'end' }`. Not known-field skipping — that answers "do I still need to ask?", while `requires` answers "may this step run at all?". They differ exactly when the customer never answers: `maxAsks` retires the field and the step proceeds with it unknown. |
 | `Signal`, `SignalContext`, `SignalFiring`, `signals`, `signalBatchSize`, `triggeredSignals` | `mention` flows, `repeat`, `claims` |
 | `ToolContext.updateContext / updateData / setField / dispatch`, `ToolResult.dataUpdate / contextUpdate / directive`, `ToolManager`, `ToolScope`, tool config helpers | `Tool.handler(args, ctx) → { value?, data? }` |
 | `PersistenceAdapter`, `SessionRepository`, `MessageRepository`, `PersistenceManager`, `SessionManager`, `restoreSession`, `createPersistedState`, `enterFlow`, `enterStep`, `completeCurrentFlow`, `mergeCollected` | `Store`, the seven `*Store` classes, `migrateSession` |
 | `SessionState`, `CollectedStateData`, `SessionData` | `Session` |
 | `AgentResponse.executedSteps / stoppedReason / endedFlows / appliedInstructions / isFlowComplete` | `TurnResult.outcomes / started / ended / skipped / messages / schedule / llmCalls` |
-| `Template` as a function, `TemplateContext`, `ConditionEvaluator`, `ConditionWhen`, `ConditionIf`, `!` exclusions | `Template = string` with `{{data.x}}` `{{context.x}}` `{{input.x}}`; `Pred` (function or JSON) |
+| `Template` as a function, `TemplateContext`, `ConditionEvaluator`, `ConditionWhen`, `ConditionIf` | `Template = string` with `{{data.x}}` `{{context.x}}` `{{input.x}}`; `Pred` (function or JSON). **`!` exclusions are not gone** — a phrase opening with `!` still rules a trigger out. Copy the list across unchanged. |
 | `Term`, `terms` | put the glossary in `knowledgeBase` or an instruction |
 | `Instruction.enabled / tags / metadata` | filter before passing |
 | `promptCache`, `PromptSectionCache`, `PromptCacheConfig` | gone; every prompt is built per call. `compaction` stays and runs once per turn on the history you pass |

package/docs/reference/actions-events-conditions.md

@@ -116,7 +116,7 @@ f.action<const P extends ParamDefs>(def: {
 
 ### Behaviour
 
-- `with` is rendered before `run` sees it. `{{data.x}}`, `{{context.x}}` and `{{input.x}}` are replaced inside every string, at any depth. A path that resolves to nothing keeps its placeholder, so a typo stays visible.
+- `with` is rendered before `run` sees it. `{{data.x}}`, `{{context.x}}` and `{{input.x}}` are replaced inside every string, at any depth. An unknown path keeps its placeholder, so a typo stays visible. A blank one drops out instead and the gap it left in the sentence closes — an empty string, or a path through a `null` (`{{context.lead.name}}` with no lead). A `null` at the end of a path is unknown, not blank.
 - `with` is checked when the agent is built, not on the turn that reaches the step. A missing required parameter, an unknown parameter, or a value outside `enum` throws `FlowConfigurationError`. So does a wrong type: `"3"` is not a number, because values are never coerced. A string that contains `{{` skips the `enum` check, because its value is only known at run time.
 - Actions run in the Run phase, by code, with zero model calls. They run while `silenced` too.
 - A `do` step whose action name is not registered throws at build. If the registry changed under a running agent, the step reports `code: 'action-failed'` with `detail: 'unknown action "notify"'`.

package/docs/start/04-add-tools.md

@@ -174,7 +174,7 @@ const agent = f.agent({
 
 `parameters` use the same `type`, `enum` and `description` as fields (plus `optional: true`), and `run` receives them already typed: `mensagem` is a `string` above, nothing to check.
 
-`with` fills the parameters. `{{data.x}}`, `{{context.x}}` and `{{input.x}}` are replaced before the action runs. A placeholder whose value is unknown stays as written, so a skipped `tamanho` reaches the seller as `{{data.tamanho}}`. Word the message without it, or fork first with an `if` step on `{ known: ["tamanho"] }`. A `do` step never talks to the model: zero calls.
+`with` fills the parameters. `{{data.x}}`, `{{context.x}}` and `{{input.x}}` are replaced before the action runs. A placeholder whose value is unknown stays as written, so a skipped `tamanho` reaches the seller as `{{data.tamanho}}`. One the host filled with an empty string drops out instead. Word the message without it, or fork first with an `if` step on `{ known: ["tamanho"] }`. A `do` step never talks to the model: zero calls.
 
 The name and the parameters are checked when the agent is built. An unknown action, or a `with` missing a required parameter, throws `FlowConfigurationError` at startup with the step id and the fix.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "4.0.0-alpha.4",
+  "version": "4.0.0-alpha.6",
   "description": "Conversational state engine for TypeScript where the AI understands, but the code is in control",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -59,7 +59,8 @@
     "release:alpha": "bun publish --tag alpha",
     "release": "bun publish",
     "test": "bun test tests/*.test.ts tests/scenarios/*.test.ts",
-    "eval:live": "bun run scripts/eval/live.ts"
+    "eval:live": "bun run scripts/eval/live.ts",
+    "eval:exclusions": "bun run scripts/eval/exclusions.ts"
   },
   "keywords": [
     "ai",

package/src/utils/template.ts

@@ -5,6 +5,14 @@
  * per-turn context) and `input` (the run's trigger payload). A path that
  * resolves to nothing keeps its placeholder, so a typo stays visible instead
  * of vanishing into an empty string.
+ *
+ * A path the host answered with nothing is a different case: it knows the
+ * field and knows it is blank. Then the placeholder goes and `tidy` closes the
+ * gap it left, so "Ola {{context.lead.name}}, tudo bem?" sends "Ola, tudo bem?"
+ * and never "Ola , tudo bem?". Two things count as blank: an empty string, and
+ * a path that walks THROUGH a null — `context.lead` being `null` means there
+ * is no lead, so "the lead's name" is blank, not mistyped. A null at the end of
+ * a path is still unknown: a field that collected nothing keeps its braces.
  */
 
 export interface TemplateScope {
@@ -15,11 +23,38 @@ export interface TemplateScope {
 
 const PLACEHOLDER = /\{\{\s*([^}\s]+)\s*\}\}/g;
 
+/** The path ran into a `null` on its way down: the container the host named is absent. */
+const ABSENT = Symbol("absent");
+
 export function render(template: string, scope: TemplateScope): string {
-  return template.replace(PLACEHOLDER, (match, path: string) => {
+  let emptied = false;
+  const out = template.replace(PLACEHOLDER, (match, path: string) => {
     const value = lookup(scope, path.split("."));
-    return value === undefined || value === null ? match : stringify(value);
+    if (value === ABSENT) {
+      emptied = true;
+      return "";
+    }
+    if (value === undefined || value === null) return match;
+    const text = stringify(value);
+    if (text === "") emptied = true;
+    return text;
   });
+  return emptied ? tidy(out) : out;
+}
+
+/**
+ * Close the hole an empty value leaves: a doubled space, a space before
+ * punctuation, a space at the end of a line.
+ *
+ * Deliberately narrow. It only runs on a string where something substituted to
+ * "", and it only collapses a run of spaces that follows a visible character,
+ * so indentation in a markdown list survives.
+ */
+function tidy(text: string): string {
+  return text
+    .replace(/(?<=\S)[ \t]{2,}/g, " ")
+    .replace(/ +([,.;:!?\u2026])/g, "$1")
+    .replace(/[ \t]+$/gm, "");
 }
 
 /** `render` over every string inside a value, recursively. Non-strings pass through. */
@@ -37,7 +72,8 @@ export function renderDeep<T>(value: T, scope: TemplateScope): T {
 function lookup(root: unknown, keys: string[]): unknown {
   let current = root;
   for (const key of keys) {
-    if (current === null || typeof current !== "object") return undefined;
+    if (current === null) return ABSENT;
+    if (typeof current !== "object") return undefined;
     current = (current as Record<string, unknown>)[key];
   }
   return current;