Architecture before and after
The prior architecture remains authoritative: AgentRouter owns entry routing; Cortex ranks knowledge, Skills and specialists; AgentManager chooses chat-v4 or direct generation. Customer360 aggregates contact activity and CustomerCase continuity; incremental conversation intelligence supplies snapshots. Dashboard Livia has a separate permission-aware orchestrator and context-brain, with briefing, opportunities, history, repository and screenshot capabilities. It is not a synonym for Customer360. The new shared module atpackages/zappway/lib/cognitive-strategy resolves a typed profile/configuration/context into a finite conversational decision. It consumes existing context, adds no LLM call and does not choose agents or execute tools. The architecture audit and source table are in docs/audits/cognitive-strategy-layer.md.
Contracts and ownership
CognitiveStrategyProfile versions are immutable; CognitiveContext contains identifiers, available actions and bounded signal indicators. CognitiveStrategyDecision contains objective, stage when configured, move, focus, evidence codes, next action and confidence. This is not chain-of-thought. Confidence is a deterministic policy score, not a calibrated probability or conversion estimate.
zappway_livia requires the canonical seed organization and allowlisted agent ID, or the authenticated context-brain server entrypoint. A copied name, client metadata or Flow payload never selects it. Dashboard Livia uses complete_request; seeded Livia defaults to activation until explicitly configured. Generic profiles have no default commercial objective. No prices, plans, offers or product claims are stored in either profile.
Natural-language intent stays with the existing LLM. All strategy instructions are in English and preserve the response locale/persona/channel rules. No regexes or translated phrase lists classify what the user supposedly intends. Optional explicit signals in the internal context represent already structured evidence, not a text detector. The response model must infer closure/human requests in the conversation language and give them priority over advisory guidance.
Configuration persists in existing Agent.interfaceConfig (interface_config) and Tool.config JSON. Zod validates the optional declarations. No Prisma migration, denormalized write or new index is required. Flow configuration is a declaration on the agent-to-Flow binding, not a new ZappFlux Flow schema. Existing Flow Builder graphs, versions, serialization and background execution remain intact. No separate Livia-only Flow engine was found; scheduled PA briefing/report/alert routines remain deterministic.
Precedence and inheritance
System/security/tenant permissions, organizational rules, explicit agent rules, tool limits and facts remain superior to strategy. chat-v4 composes its existing identity/Cortex, Skills and tool instructions before appending the short advisory block; knowledge restrictions, history and user messages retain their existing roles. Direct generation and Livia use the same composer. Free-form customer/snapshot text is never interpolated into strategy instructions. Delegation carries an internal bounded reference tied to organization, conversation and scope. The child keeps its own identity, tools and private Skills; existing parent-shared and organization Skills continue through their resolver. Child configuration can supply its own objective; inherited restrictions are unioned. Shadow cannot be promoted by delegation. The reference is not a public DTO, tool argument or response metadata field. A successfully triggered Flow can supply missing objective/stage and add restrictions for the current turn. It cannot replace the agent objective or experiment assignment. A shadow Flow emits a decision without changing the model messages or inherited reference. Guidance replaces the prior strategy block while preserving the original system instructions. There is no persisted Flow stage carried into later turns and no claim of background workflow completion.Queries and data minimization
Optional enrichment reads Conversation by its primary ID with organizationId, and ConversationIntelligenceState by its unique conversationId with organizationId. CustomerCase is loaded through the existing case relation and checked against organizationId before use. The existing conversation-context projection interprets the snapshot/case; there is no duplicate contact or payment aggregator. Existing case continuity supplies cross-channel context. Snapshots older than one hour do not select pending-question or objection moves. The optional enrichment budget is 150 ms; timeout, missing data and exceptions retain the input context. Only finite decisions enter a bounded process-local cache (256 entries, 60 seconds), keyed by tenant, conversation, turn/context/configuration and a hash of the message. Raw text is not cached by this module. It makes no new model calls. Provider billing still determines the cost of the additional short prompt block.API and privacy
The existing agent PATCH requiresagents.write and assertSameOrganization, retains the sibling update shape and validates declared scope against server identity. Public agent GET and external GET strip cognitive settings from interface configuration and Flow tools. Authorized management reads retain settings. Existing HTTP tool credential sanitization remains intact.
No configuration retrieval tool is introduced. Strategy IDs, experiment configuration and decisions are not emitted to clients. Model-visible guidance is deliberately nonsensitive; prompt secrecy cannot be guaranteed merely with a system instruction. This module does not claim to solve general prompt injection or remove unrelated existing public agent fields.
Rollout, telemetry and rollback
COGNITIVE_STRATEGY_MODE accepts disabled, shadow or enabled; unset defaults to disabled unless an agent explicitly opts in. Explicit global disabled, or COGNITIVE_STRATEGY_EMERGENCY_DISABLED=true, overrides all persisted settings. Global shadow is a rollout ceiling and cannot be promoted by an agent setting. COGNITIVE_STRATEGY_ORGANIZATIONS optionally limits rollout to comma-separated organization IDs. An empty list does not restrict organizations. Dashboard Livia additionally requires its new capability surface and existing PA emergency/canary gates; PERSONAL_ASSISTANT_COGNITIVE_STRATEGY_MODE defaults to disabled. Turbo forwards these server-only variables.
Reused Cortex telemetry records cognitive_strategy.evaluated, applied, shadowed, error and outcome. Evaluations include decision/profile/version, objective/stage, channel, agent/conversation/turn, optional Flow/experiment/cohort, selected move/action, confidence, cache hit, elapsed time, character count and estimated extra prompt tokens. No raw messages, prompts, sensitive customer data or private reasoning are logged by this module. Outcome values are response generation, successful delegation/handoff and generation error; correlate existing lead/payment/resolution events by conversation in later analysis. They are not attributed commercial conversions.
Experiment assignment is explicit configuration (id, variant, optional cohort), not a new A/B platform. Control evaluates without applying guidance. To roll back, set the global emergency switch or mode to disabled and restart/redeploy using the normal environment process. No data migration or deletion is needed.