@falai/agent 2.1.1 → 2.2.1

package/docs/guides/conditions.md

@@ -7,7 +7,7 @@ order: 1
 
 # When and if
 
-Conditions decide whether a flow activates, a step runs, an instruction renders, or a branch fires. v2 splits them into two distinct fields with different evaluators:
+Conditions decide whether a flow activates, a step runs, an instruction applies, or a branch fires. v2 splits them into two distinct fields with different evaluators:
 
 - `when` — strings the LLM evaluates against intent and the conversation. Costs tokens.
 - `if` — TypeScript predicates the engine evaluates locally. Free.
@@ -38,19 +38,19 @@ If the answer lives in `data`, `context`, or `session`, it's `if`. If the answer
 }
 ```
 
-Multiple strings combine with **AND** semantics — every clause must pass for the condition to match.
+Multiple strings combine with **OR** semantics — any clause may pass for the condition to match. Use the array form for alternative natural-language expressions of the same intent:
 
 ```typescript
 {
-  title: "Premium Refund",
+  title: "Address",
   when: [
-    "the user is requesting a refund",
-    "the user is asking about an enterprise plan",
+    "the user asked about the address",
+    "the user asked where we are located",
   ],
 }
 ```
 
-The strings are sent to the LLM as part of the routing or activation prompt. Keep them short, intent-shaped, and free of code-style boolean expressions — `"the user wants to cancel"` lands; `"data.cancelRequested === true"` does not.
+The strings are sent to the LLM as part of the routing or activation prompt. For instructions, the string is appended to the instruction bullet so the response model can apply the instruction conditionally. Keep conditions short, intent-shaped, and free of code-style boolean expressions — `"the user wants to cancel"` lands; `"data.cancelRequested === true"` does not.
 
 ## `if` — code predicates
 
@@ -120,7 +120,7 @@ The same `when` / `if` shape attaches to four primitives. Semantics are identica
 | --------------- | ----------------------- | -------------------------------------------------- |
 | Flow            | `FlowOptions.when/if`   | Whether the router selects this flow this turn     |
 | Step            | `StepOptions.when/if`   | Whether the step is reachable in the current flow  |
-| Instruction     | `Instruction.when/if`   | Whether the instruction renders into the prompt    |
+| Instruction     | `Instruction.when/if`   | Whether the instruction applies to the response    |
 | BranchEntry     | `BranchEntry.when/if`   | Whether this branch entry matches inside `step.branches` |
 
 ```typescript
@@ -160,7 +160,8 @@ A short checklist before shipping a condition:
 
 - Does it read a field, flag, or context value? Use `if`.
 - Does it interpret natural language? Use `when`.
-- Multiple clauses that all must pass? Drop them in an array — both fields AND.
+- Multiple natural-language alternatives where any may match? Put them in `when` — arrays use OR.
+- Multiple code predicates that must all pass? Put them in `if` — arrays use AND.
 - Need to skip when a value is already collected? `step.skip` (OR semantics).
 - Both fields set? `if` runs first, free; `when` only fires if `if` passes.
 

package/docs/guides/instructions.md

@@ -62,7 +62,7 @@ createAgent({
 });
 ```
 
-Reach narrows as you nest. Agent-scope instructions render on every turn for every flow. Flow-scope instructions render only while that flow is active. Step-scope instructions render only while that step is current. Conditions on `when` and `if` apply on top — an agent-scope instruction with `when: "User is angry"` still requires that activation to fire, just like a step-scope one.
+Reach narrows as you nest. Agent-scope instructions render on every turn for every flow. Flow-scope instructions render only while that flow is active. Step-scope instructions render only while that step is current. Conditions apply on top: `if` removes an instruction locally when its predicate fails, while `when` is rendered with the instruction so the model can decide whether the natural-language condition applies.
 
 The composer renders the resolved set under a single `## Instructions` heading and tags each line with a scope caption so the model can read both *what* and *where from* in one pass:
 
@@ -74,28 +74,28 @@ The composer renders the resolved set under a single `## Instructions` heading a
 
 ## Rendering format
 
-Each active instruction lands in the prompt as a single bullet:
+Each eligible instruction lands in the prompt as a single bullet:
 
 ```
-- [<kind>] [<scope>] <prompt>
+- [<kind>] [<scope>] <prompt> (apply only when: <when-clause> OR <when-clause>)
 ```
 
-A composed block looks like this:
+The condition suffix is omitted when `when` is not set. A composed block looks like this:
 
 ```
 ## Instructions
 
 - [must] [Always] Validate dates are in the future before booking.
 - [never] [Always] Promise rates you have not looked up.
-- [should] [In: Booking] Offer to compare two options before committing.
+- [should] [In: Booking] Offer to compare two options before committing. (apply only when: the user is comparing hotel options)
 - [must] [Step: payment] If the card is declined, never retry without confirmation.
 ```
 
-The format is fixed. The kind prefix is always present (defaulting to `[should]`), the scope caption is always present, and the prompt text follows verbatim. There is nothing to configure — what you write in `prompt` is what the model reads.
+The format is fixed. The kind prefix is always present (defaulting to `[should]`), the scope caption is always present, and the prompt text follows verbatim. When present, `when` clauses are joined with `OR` and appended for the model to evaluate.
 
 ## `appliedInstructions` on the response
 
-Every `respond()` call returns an `appliedInstructions` array listing exactly which instructions were rendered into that turn's prompt. The set is deterministic — it comes from the prompt composer, not the model — so you can use it for observability, audits, and tests:
+Every `respond()` call returns an `appliedInstructions` array listing exactly which instructions were rendered into that turn's prompt. The set is deterministic — it comes from the prompt composer, not the model — so you can use it for observability, audits, and tests. For an instruction with `when`, inclusion means the conditional instruction reached the model; it does not claim that the model judged the condition true:
 
 ```typescript
 const response = await agent.respond("I want to book a room.");

package/docs/reference/branches.md

@@ -19,7 +19,7 @@ Branches resolve **after** the step's post-LLM phase (tool execution, `finalize`
 
 ```typescript
 interface BranchEntry<TContext = unknown, TData = unknown> {
-  /** AI-evaluated condition. String or array of strings (AND semantics). */
+  /** AI-evaluated condition. String or array of strings (OR semantics). */
   when?: string | string[];
 
   /** Code predicate. Function or array of functions (AND semantics). */
@@ -64,7 +64,7 @@ interface BranchPredicateContext<TContext = unknown, TData = unknown> {
 
 | Field | Type | Required | Default | Notes |
 |-------|------|----------|---------|-------|
-| `when` | `string \| string[]` | no | — | AI-evaluated condition. Reuses the same machinery as `step.when`. Only evaluated if `if` passes (or is absent). Costs LLM tokens. |
+| `when` | `string \| string[]` | no | — | AI-evaluated condition. Arrays use OR semantics. Reuses the same machinery as `step.when`. Only evaluated if `if` passes (or is absent). Costs LLM tokens. |
 | `if` | `BranchPredicate \| BranchPredicate[]` | no | — | Code predicate. Free to evaluate. When both `when` and `if` are set, `if` runs first; `when` is only evaluated if all `if` predicates pass. |
 | `then` | `string \| Directive` | yes | — | Target. See [Resolution of `then`](#resolution-of-then) below. |
 | `label` | `string` | no | — | Optional label surfaced in event traces and flow visualization. |

package/docs/reference/flow.md

@@ -77,7 +77,7 @@ class Flow<TContext = unknown, TData = unknown> {
 | `id`                  | `string`                                          | no       | derived from `title` | Stable identifier. Auto-generated deterministically from the title when omitted.                                                                                 |
 | `title`               | `string`                                          | yes      | —       | Human-readable name. Shown to the router and used as the default flow id.                                                                          |
 | `description`         | `string`                                          | no       | —       | One-line summary surfaced to the router prompt.                                                                                                    |
-| `when`                | `string \| string[]`                              | no       | —       | AI-evaluated activation condition(s). Strings only — functions belong on `if`. Multiple strings combine with AND semantics.                        |
+| `when`                | `string \| string[]`                              | no       | —       | AI-evaluated activation condition(s). Strings only — functions belong on `if`. Multiple strings combine with OR semantics.                         |
 | `if`                  | `(ctx) => boolean \| Promise<boolean>` or array   | no       | —       | Code-evaluated activation condition(s). Free to evaluate. When both are set, `if` runs first; `when` only evaluates if `if` passes.                |
 | `instructions`        | `Instruction<TContext, TData>[]`                  | no       | `[]`    | Flow-scoped instructions. Apply only while this flow is active. See [Instruction](./instruction.md).                                               |
 | `tools`               | `(string \| Tool)[]`                              | no       | `[]`    | Tool ids (resolved via the agent's tool registry) or inline `Tool` objects. Available only while this flow is active.                              |

package/docs/reference/instruction.md

@@ -11,7 +11,7 @@ order: 5
 
 An `Instruction` is a single statement of behavior the agent should follow. v2 collapses three v1 types into one — every instruction now carries a `kind` discriminator (`'must'`, `'never'`, or `'should'`) and a `prompt` that is rendered into the system prompt with a scope caption. The same shape works at agent, flow, and step scope; only its position in the configuration changes.
 
-The set of instructions actually rendered into a given turn's prompt is reported back on the response as `appliedInstructions` — observability is deterministic, derived from rendering, not self-reported by the model.
+The set of instructions actually rendered into a given turn's prompt is reported back on the response as `appliedInstructions` — observability is deterministic, derived from rendering, not self-reported by the model. For instructions with a textual `when`, this means the condition was presented to the model, not that the model reported a match.
 
 ## Signature
 
@@ -19,7 +19,7 @@ The set of instructions actually rendered into a given turn's prompt is reported
 interface Instruction<TContext = unknown, TData = unknown> {
   id?: string;
   kind?: 'must' | 'never' | 'should';        // default: 'should'
-  when?: ConditionWhen;                       // AI-evaluated string(s), AND semantics
+  when?: ConditionWhen;                       // AI-evaluated string(s), OR semantics
   if?: ConditionIf<TContext, TData>;          // code-evaluated function(s), AND semantics
   prompt: Template<TContext, TData>;
   enabled?: boolean;                          // default: true
@@ -48,7 +48,7 @@ interface AppliedInstruction {
 |-------|------|----------|---------|-------|
 | `prompt` | `Template<TContext, TData>` | yes | — | Behavioral text rendered into the prompt under the `## Instructions` section. |
 | `kind` | `'must' \| 'never' \| 'should'` | no | `'should'` | Severity. `'must'` = absolute do, `'never'` = absolute don't, `'should'` = conditional nudge. |
-| `when` | `ConditionWhen` | no | — | AI-evaluated activation string (or array, AND semantics). Functions are not allowed here; use `if`. |
+| `when` | `ConditionWhen` | no | — | AI-evaluated activation string (or array, OR semantics). Functions are not allowed here; use `if`. |
 | `if` | `ConditionIf<TContext, TData>` | no | — | Code-evaluated activation function (or array). Free to evaluate. When both `when` and `if` are set, `if` runs first; `when` is only evaluated if `if` passes. |
 | `id` | `string` | no | auto | Stable identifier used in `AppliedInstruction.id`. Auto-generated when omitted. |
 | `enabled` | `boolean` | no | `true` | Set `false` to skip the instruction without removing it from configuration. |
@@ -71,12 +71,14 @@ The same `Instruction` shape attaches at three positions:
 - **Flow:** `FlowOptions.instructions` — considered when the active flow matches.
 - **Step:** `StepOptions.instructions` — considered when the active step matches.
 
-At prompt-build time the composer renders each active instruction as a single bullet:
+At prompt-build time the composer renders each eligible instruction as a single bullet:
 
 ```
-- [<kind>] [<scope-caption>] <prompt>
+- [<kind>] [<scope-caption>] <prompt> (apply only when: <when-clause> OR <when-clause>)
 ```
 
+The parenthesized condition is omitted when `when` is not set. Code-evaluated `if` predicates run first; a failing predicate removes the entire bullet before the prompt reaches the model.
+
 Scope captions are fixed by where the instruction was declared:
 
 | Scope | Caption |

package/docs/reference/step.md

@@ -96,7 +96,7 @@ interface StepLifecycleHooks<TContext = unknown, TData = unknown> {
 | `auto` | `boolean` | no | `false` | When `true`, the step runs without an LLM call — only `onEnter`, `prepare`, and `branches` execute. Cannot coexist with `prompt`, `collect`, `tools`, or `finalize`. Counts against `maxAutoStepsPerTurn`. |
 | `collect` | `(keyof TData)[]` | no | `[]` | Schema field keys this step is responsible for extracting from the user message. Every key must exist in the agent's `schema`. The engine skips the step automatically when every listed key is already present in `session.data` (pre-extraction). |
 | `requires` | `(keyof TData)[]` | no | `[]` | Prerequisite field keys. The engine refuses to enter the step until every key is present in `session.data`. When fields covered by `requires` are read inside `branches[].if` predicates, they are guaranteed to be defined. |
-| `when` | `string \| string[]` | no | — | AI-evaluated activation strings (AND semantics). Evaluated by the LLM at routing time. Functions are not allowed here — the constructor throws `FlowConfigurationError` if a function is found. |
+| `when` | `string \| string[]` | no | — | AI-evaluated activation strings (OR semantics). Evaluated by the LLM at routing time. Functions are not allowed here — the constructor throws `FlowConfigurationError` if a function is found. |
 | `if` | `(ctx) => boolean \| Promise<boolean>` or array | no | — | Code-evaluated activation predicates (AND semantics). Evaluated locally — no LLM cost. When both `when` and `if` are set, `if` runs first; `when` is only evaluated if every `if` predicate passes. |
 | `skip` | `(ctx) => boolean \| Promise<boolean>` or array | no | — | Code-evaluated skip predicates (OR semantics). When any predicate returns `true`, the step is bypassed. Only code predicates — no AI strings. |
 | `tools` | `(string \| Tool<TContext, TData>)[]` | no | `[]` | Tools available during this step. Strings are resolved against the agent's tool registry; objects are inline tools. Stacked on top of agent and flow scopes. |
@@ -130,7 +130,7 @@ or the full `Directive` surface (`appendPrompt`,
 
 For one step, the engine walks this sequence per turn:
 
-1. Evaluate `if` (code, AND) and `when` (AI, AND) — fails skip the step entirely.
+1. Evaluate `if` (code, AND) and `when` (AI, OR) — fails skip the step entirely.
 2. Evaluate `skip` (code, OR) — true means bypass and fall through.
 3. Check `requires` — refuse entry if any required field is missing.
 4. Run `onEnter`, then `prepare` / `hooks.prepare`. May emit a `Directive` (pre-LLM fields honored).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "2.1.1",
+  "version": "2.2.1",
   "description": "Conversational state engine for TypeScript where the AI understands, but the code is in control",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -38,7 +38,7 @@
   },
   "homepage": "https://falai.dev",
   "scripts": {
-    "build": "npm run build:esm && npm run build:cjs && npm run fix:cjs",
+    "build": "bun run build:esm && bun run build:cjs && bun run fix:cjs",
     "build:esm": "tsc",
     "build:cjs": "tsc --project tsconfig.cjs.json",
     "fix:cjs": "echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
@@ -48,15 +48,14 @@
     "lint": "eslint src/**/*.ts",
     "lint:fix": "eslint src/**/*.ts --fix",
     "clean": "rm -rf dist",
-    "prebuild": "npm run clean",
-    "prepublishOnly": "npm run lint && npm run typecheck && npm run build && bun run test",
-    "release:patch": "npm version patch && npm publish",
-    "release:minor": "npm version minor && npm publish",
-    "release:major": "npm version major && npm publish",
-    "release:alpha": "npm publish --tag alpha",
-    "release": "npm publish",
-    "test": "bun test tests/*.test.ts",
-    "preinstall": "node preinstall.js"
+    "prebuild": "bun run clean",
+    "prepublishOnly": "bun run lint && bun run typecheck && bun run build && bun run test",
+    "release:patch": "bun pm version patch && bun publish",
+    "release:minor": "bun pm version minor && bun publish",
+    "release:major": "bun pm version major && bun publish",
+    "release:alpha": "bun publish --tag alpha",
+    "release": "bun publish",
+    "test": "bun test tests/*.test.ts"
   },
   "keywords": [
     "ai",
@@ -81,17 +80,15 @@
     "@eslint/js": "^9.17.0",
     "@types/bun": "^1.3.0",
     "@types/node": "^20.19.22",
+    "@types/pg": "^8.15.5",
     "eslint": "^9.17.0",
     "fast-check": "^4.5.3",
     "typescript": "^5.3.3",
-    "typescript-eslint": "^8.18.2",
-    "vitest": "^3.2.4"
+    "typescript-eslint": "^8.18.2"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.65.0",
-    "@google/genai": "^0.3.0",
-    "@types/pg": "^8.15.5",
-    "@types/redis": "^4.0.11",
+    "@google/genai": "^2.7.0",
     "loglevel": "^1.9.2",
     "openai": "^6.3.0"
   },
@@ -99,10 +96,9 @@
     "@opensearch-project/opensearch": "^2.0.0",
     "@prisma/client": "^6.0.0",
     "better-sqlite3": "^11.0.0 || ^12.0.0",
-    "ioredis": "",
-    "mongodb": "",
-    "mysql2": "^3.2.0",
-    "pg": ""
+    "ioredis": "^5.0.0",
+    "mongodb": "^6.0.0",
+    "pg": "^8.0.0"
   },
   "peerDependenciesMeta": {
     "@prisma/client": {
@@ -111,18 +107,12 @@
     "ioredis": {
       "optional": true
     },
-    "redis": {
-      "optional": true
-    },
     "mongodb": {
       "optional": true
     },
     "pg": {
       "optional": true
     },
-    "mysql2": {
-      "optional": true
-    },
     "better-sqlite3": {
       "optional": true
     },
@@ -130,4 +120,4 @@
       "optional": true
     }
   }
-}
+}

package/src/adapters/SQLiteAdapter.ts

@@ -36,15 +36,15 @@ import { createSessionId } from "../utils";
  * SQLite database interface - matches better-sqlite3
  */
 export interface SqliteDatabase {
-  prepare(sql: string): SqliteStepment;
+  prepare(sql: string): SqliteStatement;
   exec(sql: string): void;
   close(): void;
 }
 
 /**
- * SQLite stepment interface
+ * SQLite statement interface - matches better-sqlite3 Statement
  */
-export interface SqliteStepment {
+export interface SqliteStatement {
   run(...params: unknown[]): { changes: number; lastInsertRowid: number };
   get(...params: unknown[]): Record<string, unknown> | undefined;
   all(...params: unknown[]): Array<Record<string, unknown>>;

package/src/adapters/index.ts

@@ -30,7 +30,7 @@ export type {
 export { SQLiteAdapter } from "./SQLiteAdapter";
 export type {
   SqliteDatabase,
-  SqliteStepment,
+  SqliteStatement,
   SQLiteAdapterOptions,
 } from "./SQLiteAdapter";
 

package/src/core/BranchEvaluator.ts

@@ -20,8 +20,8 @@ import { eventsToHistory, logger } from "../utils";
 
 /**
  * The AI condition evaluator function signature.
- * Accepts an array of condition strings (AND semantics) and returns
- * whether all conditions are satisfied.
+ * Accepts an array of condition strings (OR semantics) and returns
+ * whether any condition is satisfied.
  *
  * This is the same evaluation mechanism used by `step.when` — condition
  * strings are evaluated by the AI provider against the conversation context.
@@ -65,7 +65,7 @@ export function createAiConditionEvaluator<TContext = unknown>(
             "Condition(s):",
             conditionText,
             "",
-            "Return JSON with a single boolean field `result`: true if ALL conditions are satisfied, false otherwise.",
+            "Return JSON with a single boolean field `result`: true if ANY condition is satisfied, false otherwise.",
         ].join("\n");
 
         const result = await provider.generateMessage<TContext, { result: boolean }>({
@@ -78,7 +78,7 @@ export function createAiConditionEvaluator<TContext = unknown>(
                     properties: {
                         result: {
                             type: "boolean",
-                            description: "Whether all conditions are met based on the conversation context",
+                            description: "Whether any condition is met based on the conversation context",
                         },
                     },
                     required: ["result"],

package/src/core/Flow.ts

@@ -9,7 +9,6 @@ import type {
   FlowLifecycleHooks,
   StructuredSchema,
   Instruction,
-  Term,
   Tool,
   TemplateContext,
   ConditionEvaluationResult,
@@ -247,7 +246,8 @@ export class Flow<TContext = unknown, TData = unknown> {
   /**
    * Evaluate when/if conditions using the v2 split logic.
    * `if` (code predicate) evaluates first (free); `when` (AI) evaluates only when `if` passes.
-   * Both are combined with AND semantics.
+   * `if` predicates use AND semantics. `when` strings use OR semantics.
+   * When both fields are set, the passing `if` gate and AI match are combined with AND.
    */
   async evaluateWhen(
     templateContext: TemplateContext<TContext, TData>
@@ -367,14 +367,6 @@ export class Flow<TContext = unknown, TData = unknown> {
     return [...this.instructions];
   }
 
-  /**
-   * Get all terms for this flow
-   * @deprecated Flow-level terms removed in v2. Always returns empty array.
-   */
-  getTerms(): Term<TContext>[] {
-    return [];
-  }
-
   /**
    * Get all tools for this flow
    */

package/src/core/FlowRouter.ts

@@ -1151,7 +1151,7 @@ export class FlowRouter<TContext = unknown, TData = unknown> {
       if (candidate.step.when) {
         const whenResult = await candidate.step.evaluateWhen(templateContext);
         if (whenResult.aiContextStrings.length > 0) {
-          parts.push(`   When conditions: ${whenResult.aiContextStrings.join(", ")}`);
+          parts.push(`   When any condition matches: ${whenResult.aiContextStrings.join(" OR ")}`);
         } else if (typeof candidate.step.when === 'string') {
           parts.push(`   When this step should be completed: ${candidate.step.when}`);
         }
@@ -1436,7 +1436,7 @@ export class FlowRouter<TContext = unknown, TData = unknown> {
           if (step.when) {
             const whenResult = await step.evaluateWhen(templateContext);
             if (whenResult.aiContextStrings.length > 0) {
-              stepInfo.push(`   When conditions: ${whenResult.aiContextStrings.join(", ")}`);
+              stepInfo.push(`   When any condition matches: ${whenResult.aiContextStrings.join(" OR ")}`);
               activeStepConditionContext.push(...whenResult.aiContextStrings);
             } else if (typeof step.when === 'string') {
               stepInfo.push(`   When this step should be completed: ${step.when}`);

package/src/core/PromptComposer.ts

@@ -2,7 +2,6 @@ import type { Event, Term, Instruction, AgentOptions, ScopedInstructions, Applie
 import type { Flow } from "./Flow";
 import { render, renderMany, formatKnowledgeBase, createTemplateContext } from "../utils/template";
 import { TemplateContext } from "../types/template";
-import { ConditionEvaluator } from "../utils/condition";
 import { PromptSectionCache } from "./PromptSectionCache";
 import { logger } from "../utils";
 
@@ -155,8 +154,6 @@ export class PromptComposer<TContext = unknown, TData = unknown> {
     // Reset the per-turn applied set
     this.lastAppliedInstructions = [];
 
-    const evaluator = new ConditionEvaluator(this.renderContext);
-
     /**
      * Evaluate a single instruction's `if` code predicate(s).
      * Returns true if all predicates pass (AND semantics).
@@ -182,17 +179,6 @@ export class PromptComposer<TContext = unknown, TData = unknown> {
       return true;
     };
 
-    /**
-     * Evaluate a single instruction's `when` condition.
-     * Returns true if the instruction should be active.
-     */
-    const evaluateWhen = async (when: Instruction<TContext, TData>['when']): Promise<boolean> => {
-      if (when === undefined) return true;
-      const evaluation = await evaluator.evaluateCondition(when, 'AND');
-      if (!evaluation.hasProgrammaticConditions) return true;
-      return evaluation.programmaticResult;
-    };
-
     /**
      * Resolve the kind prefix for rendering.
      * Default kind is 'should'.
@@ -203,7 +189,7 @@ export class PromptComposer<TContext = unknown, TData = unknown> {
     };
 
     /**
-     * Process a scope bucket: filter enabled, evaluate when, collect active lines and applied records.
+     * Process a scope bucket: filter enabled, gate by `if`, render `when`, and collect applied records.
      */
     const processScope = async (
       items: Instruction<TContext, TData>[],
@@ -219,14 +205,17 @@ export class PromptComposer<TContext = unknown, TData = unknown> {
         const ifPassed = await evaluateIf(g.if);
         if (!ifPassed) continue;
 
-        // Evaluate `when` (AI condition) only when `if` passed
-        const active = await evaluateWhen(g.when);
-        if (!active) continue;
-
         const text = await render(g.prompt, this.renderContext);
         if (!text) continue;
 
-        lines.push(`- ${kindPrefix(g.kind)} ${caption} ${text}`);
+        const whenContextStrings = g.when
+          ? (Array.isArray(g.when) ? g.when : [g.when])
+          : [];
+        const condition = whenContextStrings.length > 0
+          ? ` (apply only when: ${whenContextStrings.join(" OR ")})`
+          : "";
+
+        lines.push(`- ${kindPrefix(g.kind)} ${caption} ${text}${condition}`);
         this.lastAppliedInstructions.push({
           id: g.id || '',
           scope,

package/src/core/PromptSectionCache.ts

@@ -7,19 +7,8 @@
  * directives, available tools) are recomputed on every resolveAll() call.
  */
 
-/** Section type: static sections are cached, dynamic sections recompute every turn */
-export type PromptSectionType = "static" | "dynamic";
-
-/** Configuration for prompt section caching behavior */
-export interface PromptCacheConfig {
-    /** Whether to enable section memoization (default: true) */
-    enabled?: boolean;
-    /** Keys of sections that should always recompute every turn, even if registered as static */
-    volatileKeys?: string[];
-}
-
-/** Compute function that produces a section's content */
-export type SectionCompute = () => string | null | Promise<string | null>;
+import type { PromptSectionType, PromptCacheConfig, SectionCompute } from "../types/prompt-cache";
+export type { PromptSectionType, PromptCacheConfig, SectionCompute } from "../types/prompt-cache";
 
 /** Internal entry tracking a registered section */
 interface PromptSectionEntry {